快速上手

1. 安装

keygrant 需要 Python 3.10 或更高版本。将它作为独立工具安装：

uv tool install keygrant      # 或：pipx install keygrant

macOS 自带 Python 3.9，因此直接 pip install 会失败。uv 会自动获取合适的 Python 版本。

验证是否可用：

keygrant list                 # 全新安装时输出 "(vault empty)"

2. 接入项目

在 agent 工作的项目目录中运行：

keygrant init

它会做两件事，重复执行也是安全的：

在项目的 .mcp.json 中添加一个 keygrant server，保留已有的其他 server；
在 CLAUDE.md 末尾追加一小段指引，告诉模型以环境变量的形式引用密钥，并且永远不要让你粘贴密钥。

3. 存入密钥

密钥值从 stdin 读取，因此不会出现在 shell 历史或进程列表中：

echo "sk-test-..." | keygrant set STRIPE_KEY --desc "stripe, test mode"

从剪贴板粘贴，而不是手动输入密钥值：

pbpaste | keygrant set STRIPE_KEY --desc "stripe, test mode"          # macOS
Get-Clipboard | keygrant set STRIPE_KEY --desc "stripe, test mode"    # Windows PowerShell
xclip -o -selection clipboard | keygrant set STRIPE_KEY               # Linux

描述是 agent 能看到的内容，所以要写得有用：哪个服务、哪个环境、可以用来做什么。

4. 在 Claude Code 中使用

在该目录中重启 Claude Code，让它加载新的 MCP server，然后用自然语言提问：

用 STRIPE_KEY 列出最近五笔 Stripe 扣款。

模型会调用 exec_with_secrets，命令类似 curl https://api.stripe.com/v1/charges -u "$STRIPE_KEY:"。随后会弹出一个对话框，显示的正是这条命令。读一遍，然后点击 Allow（Windows 上是 Yes）。返回的输出中，密钥已被脱敏。

15 分钟内再次运行完全相同的命令不会再次询问；任何不同的命令都会。参见审批与授权。

5. 手动试一试（可选）

你也可以在终端里自己执行同样的注入。CLI 直接运行命令，不经过 shell，所以要用 shell 包一层才能展开变量：

keygrant exec --redact STRIPE_KEY -- sh -c 'curl -s https://api.stripe.com/v1/charges -u "$STRIPE_KEY:"'
keygrant exec --redact STRIPE_KEY -- cmd /c "echo %STRIPE_KEY%"   # Windows：输出 [STRIPE_KEY:REDACTED]

CLI 每次运行都会请求审批；它从不复用授权。