故障排查

在 macOS 上安装失败

macOS 自带 Python 3.9，而 keygrant 需要 3.10+。请使用 uv tool install keygrant（它会下载合适的 Python），而不是 pip install。

Claude Code 看不到这些工具

• 运行 keygrant init 后重启 Claude Code：它在启动时读取 .mcp.json。
• 检查 server 能否单独启动：keygrant-mcp 应当停在那里等待输入（按 Ctrl+C 退出）。如果提示 “Command not found”，说明工具目录不在 PATH 中；请在 .mcp.json 中使用 uv tool dir 给出的绝对路径。
• 在 Claude Code 中，/mcp 会列出已连接的 server。

模型粘贴或打印出了密钥值

这个值来自 keygrant 之外的地方：agent 读取过的 .env 文件，或者你 shell 环境里的某个值。只有当密钥值存放在 keygrant 中时，keygrant 才能让它们不进入上下文。用 keygrant set 把它们迁移进来，删除 .env 中的副本，并确保 CLAUDE.md 中有那段指引（keygrant init 会添加）。

CLI 中 $NAME 没有被展开

keygrant exec 直接运行命令，不经过 shell。用 shell 包一层：

keygrant exec --redact KEY -- sh -c 'echo "$KEY"'        # macOS, Linux
keygrant exec --redact KEY -- cmd /c "echo %KEY%"        # Windows

“command is longer than 2000 characters”

过长的命令无法在对话框里审查，所以会被拒绝。把逻辑放进脚本文件，先读一遍，再批准运行该脚本。

对话框始终不出现

• Linux：安装 zenity。没有它就不会有本地对话框，请求会被拒绝（或发送到你的手机审批器）。
• 远程会话：对话框出现在运行 MCP server 的那台机器上，通过 SSH 使用时就是远程主机。请使用手机审批器。

请求已被拒绝，agent 却一直在问

不应该出现这种情况：工具会告诉它不要重试。如果它仍然重试，直接在聊天里指出来；无论如何，对该请求而言，拒绝都是最终结果。

退出码

keygrant exec 在用法错误时以 2 退出；密钥不存在或发生其他错误时以 1 退出；访问被拒绝时以 3 退出；其余情况返回命令自身的退出码。

报告 bug

在 GitHub 上提交 issue。涉及安全的问题，请改为参阅安全。