我把 API 密钥粘贴进了编程智能体，现在怎么办？

先轮换或撤销密钥，再处理智能体历史记录中的副本，最后设置 zn-gate，让下一次的密钥在模型看到之前就被拦截或替换为标记。

查看 .md

你在编程智能体的聊天中输入或粘贴了一个 API 密钥，或者智能体从文件中读取了它。这个密钥现在已经在发送给模型的对话里，很可能也在智能体保存在你磁盘上的历史记录里。本页按重要性的顺序给出步骤：先轮换密钥，再清理副本，最后防止再次发生。

1. 先轮换或撤销密钥

在做其他任何事之前先做这一步。删除聊天或历史文件，并不能撤回已经发送给模型提供商或已存入备份的副本。只有撤销密钥，才能让泄露的值失效。

  1. 打开签发该密钥的服务的控制台。 在它的 API 密钥、令牌或访问密钥列表中找到这个密钥。
  2. 如果有服务依赖旧密钥，先创建新密钥。 如果线上服务在使用这个密钥，而你无法接受服务中断，请先创建替代密钥，让你的应用切换到新密钥，更新所有其他使用该密钥的地方（CI 密钥、部署设置、团队成员），然后再撤销旧密钥。AWS、GitHub 和 Google Cloud 在各自的页面中都描述了这个顺序。如果没有任何东西依赖该密钥，请立即撤销。
  3. 撤销或删除旧密钥。 不要“暂时”让它保持有效。
  4. 只给新密钥它所需的最小权限。
  5. 把新密钥存放在智能体读取不到的地方。 不要放在聊天里，也不要放在智能体可以打开的普通 .env 文件里。见下面的第 3 步。
  6. 查看服务提供商针对旧密钥的使用或访问日志。 如果出现你不认识的请求，请把该账户视为已被入侵，并按照提供商的指引处理。

在哪里撤销，以下是各提供商自己的文档：

提供商 其文档的说法
AWS Updating IAM user access keys：创建第二个密钥，让应用切换到它，停用第一个密钥，在不再需要时将其删除。
GitHub Remediating a leaked secret：分步指南，包括撤销该机密、找出使用它的服务以及检查是否有未经授权的访问。令牌在 Managing your personal access tokens 中管理。
Google Cloud API keys：该页面说明如何轮换密钥（会创建一个限制相同的新密钥），以及在应用都改用新密钥后如何删除旧密钥。
Stripe API keys：如何滚动更新（roll）密钥，以及旧密钥何时失效。
Anthropic API key best practices：如果你怀疑密钥已泄露，请在 Claude Console 的 API 密钥页面中通过 “Delete API key” 撤销它。

对于这里没有列出的服务，请打开它自己的文档，搜索如何撤销、轮换或滚动更新密钥。我们只链接我们能够打开并阅读的页面。

2. 清理留在你电脑上的副本

Claude Code、Codex CLI、Cursor 和 OpenCode 都会保存你的对话历史，你输入的或经过某个工具的密钥可能就在其中。Claude Code 还会把你输入的每个提示词保存在单独的提示词历史文件里。每个智能体保存历史的位置不同，控制方式也不同，其中一些的文档对本地路径和保留期限没有任何说明。

我们把这部分集中在一篇指南里，这样只需要在一个地方保持准确：编程智能体会把你的 API 密钥留在对话记录里吗？ 它根据各厂商的文档列出四个智能体各自保存历史的位置、保留多长时间、各厂商关于上传的说明、如何找到包含密钥的文件并删除它们，以及容易被忘记的副本，例如备份和主目录的云同步。

请在第 1 步之后做这一步，而不是代替第 1 步。

3. 用 zn-gate 防止下一次

zn-gate 是位于你的编程智能体和它所用工具之间的本地层。它在你的电脑上运行，不需要账户。它的密钥 Scrubber 在 zn-gate 1.5.0 及更高版本中可用（Windows 上为 1.5.1 或更高版本），支持 Claude Code、Codex CLI、Cursor（IDE）和 OpenCode。它能修改哪些内容，因智能体而异。

对你即将粘贴的密钥，它做什么

根据 Scrubber 与密钥保险库 页面：

  • 粘贴的提示词、文件读取、命令输出、搜索结果和 MCP 工具结果，在到达模型之前都会经过 Scrubber。它认识的值（来自保险库和你的 .env 文件）以及 60 多种机密格式，会变成稳定的标记，例如 __ZN_AWS_KEY_1__，因此在智能体允许 zn-gate 改写的地方，模型拿到的是标记而不是真实的值（见下面的限制）。
  • 钩子会阻止读取包含真实值的 .env 文件，以及 ~/.aws/credentials 或 ~/.ssh/id_* 这样的凭据文件。文档称这是一道护栏，而不是沙箱。
  • 真实的值保存在你电脑上的加密保险库里。智能体使用标记，只有在你允许的地方才会填入真实值。

粘贴到提示词中的机密在这四个智能体中都会被阻止，所以该提示词不会到达模型。阻止并不会把你输入的内容从你自己的电脑上删除：智能体可能会在本地保留该提示词（Claude Code 会以明文把它保存在对话记录里）。只有经 zn-gate 清理的工具输出中才会出现标记。

放在 MCP 服务器 env 或 headers 里的令牌是另一种情况：MCP 配置里的明文令牌：如何把它们移出去说明了如何把它们从配置文件中移出去。

设置

你需要 Node.js 18 或更高版本。在你自己的终端中运行：

npx -y zn-gate init
npx -y zn-gate unlock
npx -y zn-gate env shadow .env
npx -y zn-gate check
  • init 会在你的电脑上找到这四个智能体，显示每个尚未受保护的智能体的设置，并在你确认之后执行每一步。
  • unlock 在第一次运行时创建保险库。使用系统钥匙串时，它需要一个交互式终端。
  • env shadow .env 把 .env 文件中的值移入保险库。文件里保留 __ZN_STRIPE_KEY__ 这样的标记。
  • check 在临时文件夹里用一个假机密做测试，并告诉你哪个智能体没有受到保护。不会向任何地方发送任何内容。输出的含义。

如果只想添加一个机密，又不想把它粘贴到聊天里或写在命令行上，请在隐藏的提示中输入：zn secret set GITHUB_TOKEN --host api.github.com。文档说明切勿把机密作为参数传入。

要用假值试一试，请在一个空文件夹中打开你的智能体，并把 AWS 文档中的示例密钥 AKIAIOSFODNN7EXAMPLE 粘贴到提示词里。如果 zn-gate 识别这个格式，提示词会被阻止。如果没有被阻止，可能是 zn-gate 不检测这种格式，而这个测试并不能说明你的真实密钥会怎样。

zn-gate 做不到的事

这些限制来自 Scrubber 与密钥保险库 页面和 zn-gate 的威胁模型。

  • 它不会清理在你安装它之前写下的对话记录。你今天粘贴的密钥会一直留在其中，直到你把它们删除（第 2 步）。
  • 它不会撤销任何东西，也无法控制智能体厂商在其服务器上保存什么。轮换始终是第 1 步。
  • Scrubber 能找到已知的值和可识别的格式。没有已知格式、又不在保险库或 .env 文件中的机密可能会漏过。
  • 在 Cursor 中，只能改写 MCP 工具的输出。那里不会清理 shell 输出和文件内容。
  • 有些智能体会保留自己的本地副本。Codex 的会话日志保留原始输出。
  • 在 Claude Code 中，被 zn-gate 阻止的提示词会以明文留在对话记录里，Claude Code 自己的文档也是这样说的。

常见问题

如果我已经删除了对话，还需要轮换密钥吗？ 需要。删除本地文件并不能移除已发送给模型提供商或已存入备份的副本。请先撤销密钥。

我能只删除对话记录而继续使用这个密钥吗？ 不安全。密钥已作为对话的一部分发送给了模型，请把它视为已暴露。

zn-gate 会移除已经在我历史记录里的密钥吗？ 不会。它只作用于新的提示词和工具输出。已有的历史文件保持原样。

zn-gate 会阻止我粘贴密钥吗？ 在 Claude Code、Codex CLI、Cursor 和 OpenCode 中，当它识别出格式时，会阻止粘贴到提示词里的机密。格式它不认识的机密可能会漏过，所以无论如何都要让密钥远离聊天。

如何移除 zn-gate 的钩子？ zn hooks uninstall <智能体>，例如 zn hooks uninstall codex。

相关页面

来源