keywarden

你的 AI 智能体可以使用你的 API 密钥。但它永远无法读取它们。

keywarden 是一个本地加密凭据库，支持 MCP 协议。 Claude Code、Claude Desktop、Cursor 或任何 MCP 客户端连接到它后可以获得两项能力： 发起一次经过身份验证的 API 调用，以及使用注入到环境变量中的凭据运行一条命令。这两项操作 都不会把凭据本身放入模型的上下文之中。

这里没有 get_secret 工具。这个缺失正是整个产品的意义所在。

   agent                keywarden                    upstream
     |                     |                          |
     |  "POST /v1/chat     |                          |
     |   using openai/prod"|                          |
     |-------------------->|                          |
     |                     | check policy             |
     |                     | decrypt key              |
     |                     | attach Authorization     |
     |                     |------------------------->|
     |                     |<-------------------------|
     |  response only      | scrub any key from body  |
     |<--------------------| append to audit log      |

为什么

目前，让智能体使用你的 OpenAI 密钥的标准做法，是把密钥放在 .env 文件中，然后让智能体去读取它。 但密钥进入模型上下文窗口的那一刻，它就已经进入了提供商的日志，可能进入训练集，可能进入崩溃报告， 而且肯定已经留在你的对话历史里——就是那个你六个月后要粘贴到 bug 报告里的历史。

轮换密钥很烦人。但不知道它是否泄露更让人糟心。

keywarden 直接省去了模型看到密钥的这一步。

Related MCP server: AgentPay MCP Server

安装

npm install -g keywarden

需要 Node.js 20.10 或更高版本。两个运行时依赖：MCP SDK 和 zod。没有原生模块，没有编译器， 没有守护进程。

快速开始

keywarden init --passphrase
keywarden add openai/prod --provider openai
keywarden mcp-config

init 会创建 ~/.keywarden/ 目录，其中包含一个加密的凭据库和默认拒绝的策略。add 会逐项提示 输入每个字段，因此不会在你的 shell 历史中留下任何痕迹。mcp-config 会打印出需要粘贴到 MCP 客户端中的配置块。

然后，在 Claude Code 中：

使用我的生产密钥调用 OpenAI models 端点，并告诉我可以访问哪些模型。

模型会以 ref: "openai/prod" 调用 http_request。keywarden 附加密钥、发起调用、 返回响应。如果你让它打印密钥，它会告诉你它做不到。

智能体获得的工具

设置 KEYWARDEN_DISABLE_EXEC=1 可完全移除 run 命令，仅暴露 HTTP 代理。

三个界面，一种授权模型

同一个凭据库、策略引擎、授权和审计日志可以通过三种方式访问。使用哪种方式 不会改变允许执行的操作。

HTTP 界面是 keywarden 能够从不支持 MCP 的代码中使用的关键，也是 keywarden 能够区分不同调用方的第一种方式：

keywarden apikey create ci-runner --ref 'openai/**' --http --audit --ttl 30d
keywarden serve --port 8787

curl -s http://127.0.0.1:8787/v1/proxy/openai%2Fprod \
  -H "Authorization: Bearer kw_live_..." \
  -H "content-type: application/json" \
  -d '{"method":"POST","url":"/v1/chat/completions","body":{"model":"gpt-4o","messages":[]}}'

调用方持有一个作用域为 openai/** 的 keywarden 密钥，只携带被授予的能力， 30 天后过期，一条命令即可撤销。它永远不会持有 OpenAI 密钥。路由： /v1/secrets、/v1/secrets/:ref、/v1/proxy/:ref、/v1/run、/v1/audit、 /v1/usage、/v1/whoami、/healthz。

服务器绑定 127.0.0.1，并且在没有 --allow-remote 参数时拒绝绑定到可路由接口， 因为任何能访问该端口的人都能获得该密钥所覆盖的每个凭据的授权预言机。

谁用了什么，花了多少钱

审计日志中的每条记录都包含一个操作者，而操作者信息在哈希内部，因此无法在不破坏链的情况下 重写归属信息。每个代理响应都会被解析，以获取提供商报告的令牌数量。

keywarden usage --since 7d

CREDENTIAL        CALLS          IN         OUT       TOTAL
openai/prod         142     418,220      96,410     514,630
anthropic/prod       38      92,004      31,887     123,891

ACTOR             CALLS          IN         OUT       TOTAL
http:ci-runner      118     356,900      74,220     431,120
mcp:mcp-client       62     153,324      54,077     207,401

keywarden 记录的是令牌数，而不是金额。价格会变化，因合同而异，过时的硬编码费率 会在财务报告中产生一个自信的错误数字。请注意，run 无法计量：一旦凭据 进入子进程，keywarden 只能看到退出代码，而看不到令牌数。

使用凭据的两种方式

代理，适用于 HTTP API。智能体描述请求，keywarden 附加凭据并发起 调用。适用于 OpenAI、Anthropic、Stripe、GitHub、Slack、Cloudflare、Vercel、Supabase 以及 任何使用请求头或查询参数进行身份验证的 API。

// what the agent sends
{ "ref": "openai/prod", "method": "POST", "url": "/v1/chat/completions", "body": { "model": "gpt-4o", "messages": [] } }

注入，适用于其他所有场景。AWS 需要 SigV4 请求签名，Postgres URL 根本不是 HTTP， 而 terraform apply 需要真实的环境变量。keywarden 自己启动进程：

{ "command": "aws", "args": ["s3", "ls"], "inject": ["aws/prod"] }

子进程会获得 AWS_ACCESS_KEY_ID 等环境变量。模型获得 stdout，其中出现的任何凭据 都会在输出时被屏蔽。

策略

~/.keywarden/policy.json 决定哪些凭据可以被使用、被哪个能力使用、针对什么目标使用。 规则从上到下求值，第一个匹配的规则生效，默认是拒绝。

{
  "version": 1,
  "default": "deny",
  "redactResponses": true,
  "rules": [
    {
      "ref": "openai/**",
      "http": { "allow": true, "methods": ["POST"], "paths": ["/v1/**"] },
      "exec": { "allow": false, "commands": [] },
      "rateLimitPerMinute": 30
    },
    {
      "ref": "aws/prod",
      "http": { "allow": false },
      "exec": { "allow": true, "commands": ["aws", "terraform"] },
      "rateLimitPerMinute": 10,
      "expiresAt": "2026-12-31T00:00:00.000Z"
    }
  ]
}

或者通过 CLI：

keywarden policy allow "openai/**" --http --path "/v1/**" --method POST
keywarden policy allow aws/prod --exec aws --exec terraform --arg-deny "s3://*"
keywarden policy test aws/prod exec terraform

* 匹配单个路径段内的内容，** 跨路径段匹配。expiresAt 使规则临时生效。

仅指定命令名称是不够的。将 aws 加入白名单以允许 aws s3 ls，同一个二进制文件 就可以执行 aws s3 cp 将文件复制到别人拥有的存储桶中。这就是 MCP 威胁 文献中反复指出的序列级漏洞：每一次单独调用都是经过授权的，但组合起来就是 数据泄露。因此，规则也约束参数：

"exec": {
  "allow": true,
  "commands": ["aws"],
  "argsDeny": ["s3://*", "--endpoint-url"],   // any match refuses the call
  "argsAllow": ["s3", "ls", "--region", "*"]  // if set, every argument must match
}

授权：临时、过期、限制使用次数的访问

策略是常驻配置。它不适合"让智能体做这一件事，现在，十五分钟"这种场景， 而这通常意味着放宽规则然后忘记收紧。

授权是一种携带自身限制的能力，借鉴了 macaroon 和 biscuit 的思路，由你在终端中签发：

keywarden grant aws/prod --exec aws --ttl 15m --uses 5 --arg-deny "s3://*"
keywarden grant openai/prod --http --path "/v1/chat/**" --method POST --ttl 1h --uses 20
keywarden grant list
keywarden grant revoke <id>

授权会自行过期，使用预算用尽后失效，并使用从你的凭据库派生的密钥进行 HMAC 签名， 因此手动编辑的 grants.json 会被拒绝而不是被接受。被拒绝的尝试 不会消耗使用次数。

在策略规则上设置 "requireGrant": true，常驻配置就变成了必要但不充分的条件： 在你签发授权之前什么都不会发生。这就是人在环审批步骤， 无需在 stdio 服务器中进行交互式提示。

配置完整性

加密机密只是工作的一半。policy.json 决定凭据是否可以使用， providers.json 决定凭据被发送到哪里。两者都是纯文本文件。无法解密单个 字节的人仍然可以添加一个主机指向自己的提供商，并将你的凭据重定向到那里。

因此，凭据库会固定两个文件的哈希值，并且在你查看更改之前拒绝基于其中任何一个文件执行操作：

keywarden trust show    # what drifted
keywarden trust         # review, then pin the current contents

凭据库文件整体进行 MAC 签名，而不仅仅是逐字段签名，因为将 provider: "openai" 改为其他值永远不会触及密文，否则会通过验证。

keywarden 实际强制执行的内容

• 没有明文工具。 MCP 界面没有返回凭据值的代码路径。

• 出口白名单。 凭据只能发送到其提供商声明的主机，以及你在 策略中添加的主机。提示注入让智能体将你的密钥 POST 到 attacker.example 会在主机检查时失败，甚至不会触达网络。

• 仅 HTTPS，不跟随重定向。 302 到其他源不会在外部重放你的 Authorization 请求头。

• SSRF 防护。 回环地址、私有地址段、CGNAT 和链路本地地址（包括 169.254.169.254 云元数据端点）都会被阻止，并且地址会在套接字实际使用的 DNS 查找中进行验证，因此 DNS 重绑定不会打开窗口。

• 无 shell。 run 将 argv 数组传递给 spawn，并设置 shell: false。没有 元字符解析可注入。

• 构造的子进程环境。 子进程获得继承变量的白名单以及 注入的变量。你的其他机密和 keywarden 自己的密码短语不会被继承。

• 输出脱敏。 每个工具结果都会扫描已知的凭据值、其 base64 和 URL 编码形式，以及大约十几种众所周知的密钥格式。这是纵深防御，不是主要控制措施。

• 防篡改审计。 每个决策（允许或拒绝）都会追加到哈希链日志中。 keywarden audit verify 重新计算链并报告第一个被修改或删除的条目。

• 全文件完整性。 凭据库（包括其元数据）都经过 MAC 签名，因此凭据无法在 不被检测到的情况下被重定向到其他提供商。policy.json 和 providers.json 的哈希值 被固定到凭据库中，当它们被带外更改时会拒绝使用。

• 环境加固。 当设置 NODE_TLS_REJECT_UNAUTHORIZED=0、 NODE_OPTIONS 或 SSLKEYLOGFILE 时，服务器拒绝启动，并在设置 NODE_EXTRA_CA_CERTS 和 HTTPS_PROXY 时发出警告。针对 Claude Code 的 CVE-2026-21852 就是一个环境覆盖，它重定向了带有 Authorization 请求头的出站流量； 当请求路径不受控制时，一个负责附加凭据的进程绝不能启动。

• 参数约束。 argsAllow / argsDeny 缩小了白名单命令哪些调用是 允许的，而不仅仅是哪个二进制文件。

• 衰减授权。 过期、限制使用次数、操作员签发的能力，通过 凭据库派生的 MAC 实现防伪。

• 不可信数据框架。 代理响应体被标记为来自指定主机的不可信内容， 因此 API 响应中注入的指令会作为数据呈现给模型。

加密

信封加密，全部来自 node:crypto，没有第三方加密库。

• 一个随机的 256 位数据密钥使用 AES-256-GCM 加密每个字段，凭据的引用和 字段名作为附加认证数据，因此密文无法在凭据库条目之间移动。

• 数据密钥由使用 scrypt 在 N=2^17, r=8 下从你的密码短语派生的密钥包装， 大约 128 MiB，每次尝试大约需要一秒钟。这是故意的：凭据库文件是攻击者 带走的东西，因此离线猜测必须代价高昂。

• 轮换你的密码短语会重新包装 32 个字节。它不会重新加密每个机密。

凭据库模式

--passphrase 是强模式。MCP 服务器需要在其环境中设置 KEYWARDEN_PASSPHRASE 才能无提示解锁。

--keyfile 将一个随机密钥写入 ~/.keywarden/masterkey，这样就不需要提示了。这 很方便，但也意味着任何能读取你主目录的人都可以打开凭据库。它仍然比 分散在各项目中的明文 .env 文件好得多，因为密钥在一个地方， 其使用受策略门控，并且每次使用都有日志记录。要清楚自己做了哪种权衡。keywarden doctor 会 提醒你。

在 Windows 上，文件模式会被设置，但不会像 POSIX 强制执行 0600 那样强制执行。请参阅 THREAT_MODEL.md。

CLI

keywarden init --passphrase|--keyfile   create the vault
keywarden doctor                        check the install, flag weak settings
keywarden trust [show]                  re-pin policy.json + providers.json after reviewing a change
keywarden grant <ref> ...               issue a temporary, use-capped capability
keywarden grant list | revoke <id>
keywarden add <ref> --provider <id>     store a credential (prompts for each field)
keywarden list                          metadata only
keywarden describe <ref>                metadata plus how it can be used
keywarden reveal <ref>                  print plaintext, asks first, always audited
keywarden rm <ref> [--field f]          delete
keywarden exec <ref[,ref]> -- <cmd>     run a command with credentials injected
keywarden policy show|init|allow|deny|test
keywarden audit [tail|verify]
keywarden passphrase                    rotate
keywarden providers                     built-in presets
keywarden mcp-config                    print the MCP client config
keywarden doctor                        check the install, flag weak settings

自定义提供商

任何未内置的内容都放在 ~/.keywarden/providers.json 中。请参阅 docs/PROVIDERS.md。

{
  "acme": {
    "label": "Acme Internal API",
    "hosts": ["api.acme.internal", "*.acme.io"],
    "baseUrl": "https://api.acme.io",
    "fields": ["token", "tenant"],
    "required": ["token"],
    "auth": { "type": "header", "name": "X-Acme-Key", "template": "{{token}}" },
    "env": { "ACME_TOKEN": "{{token}}", "ACME_TENANT": "{{tenant}}" }
  }
}

keywarden 无法保护你免受什么

在信任它处理任何重要事务之前，请阅读 THREAT_MODEL.md。简而言之：

• 如果代理能够通过某个其他工具运行任意本地命令，它就能读取你的 vault 文件，并且在 keyfile 模式下读取你的主密钥。keywarden 保护的是模型的上下文，而不是你的磁盘。

• run 会把凭据交给一个真实进程。如果你将某个命令加入白名单，而该命令可能被引导去泄露其自身环境变量，凭据就会外泄。白名单要收窄。

• 脱敏是一道有漏洞的安全网。如果 API 以我们无法识别的某种方式重新编码后返回凭据，它将无法被捕获。

• keywarden 不会阻止代理使用其被合法允许使用的凭据去做代价高昂或具有破坏性的事情。这正是策略范围和速率限制的用途。

开发

npm install
npm run build
npm test          # 89 unit tests + 46 end-to-end checks against the real CLI, MCP and HTTP servers

e2e 测试套件在一个一次性的 KEYWARDEN_HOME 中驱动实际的二进制文件，并断言（除其他事项外）没有任何工具响应包含该凭据。

阅读

• THREAT_MODEL.md — 哪些在范围内，哪些坦率地说不在

• docs/RESEARCH.md — 该设计所依据的 2026 年文献，采纳了什么，考虑过什么又被否决了什么

• docs/COMPETITORS.md — 竞争格局，以及 keywarden 真正与众不同的地方，而不仅仅是营销上的差异

• docs/TEAM.md — 多开发者架构：身份、无可读服务器的密钥共享、审批工作流、成本核算以及构建顺序

• docs/PROVIDERS.md — 编写自定义 provider

托管版

计划为需要团队 vault、基于浏览器的管理以及跨机器同步的用户提供托管版本，并保持相同的零暴露保证。本仓库中的所有内容保持 MIT 许可，并且完全可独立使用。参见 docs/HOSTED.md。

许可证

MIT