FAQ.md

常见问题与故障排查

KeyBroker 是密码管理器吗？

不是传统密码管理器。它不提供浏览、复制或自动填充明文密码，重点是让 AI 通过受约束能力使用凭据。当前版本也是预审计候选版。

AI 能否通过 Handle 推算出密钥？

不能。Handle 是随机引用，不包含密钥内容。但同一 Windows 用户下的恶意软件仍可能攻击本机进程或账户，这不在当前隔离边界内。

为什么不直接把 ${SECRET} 替换为真实值？

全局替换无法可靠判断目标、上下文和传播范围，容易把密钥写入错误命令、日志或文件。KeyBroker 只允许结构化且预先批准的操作。

为什么每次都要审批？

审批让用户确认 AI 的当前意图与已保存策略一致。候选版只实现每次审批，没有“永远允许”模式。

为什么没有 reveal/export？

任何返回明文的接口都会使模型、MCP 客户端和日志重新成为密钥传输通道，违背项目核心目标。

Handle 可以公开吗？

Handle 不是凭据，但仍会泄露“某个密钥条目存在”这一元数据，不建议发布到公共日志或文档。

备份能否在另一台电脑恢复？

不保证。v1 备份的密钥由 Windows DPAPI CurrentUser 保护，通常绑定用户配置文件。它主要用于同一用户环境中的损坏恢复。

可执行文件升级后 CLI Profile 为什么失效？

因为 Profile 固定了 SHA-256。升级可能是正常变化，也可能是供应链篡改；必须人工验证新文件后更新 Profile。

请求提示 origin/path 不允许怎么办？

不要直接把 Origin 或路径放宽为全部。先确认最终 HTTPS URL，无重定向地把精确 Origin 和最小路径前缀加入策略。

为什么私有网络请求默认失败？

这是为了降低 SSRF 和误访问本地管理接口的风险。只有明确需要且充分理解目标时才启用私网访问策略。

MCP 启动失败怎么办？

1. 使用 keybroker doctor 检查守护进程。
2. MCP command 使用绝对路径。
3. 确认 keybroker-mcp.exe、keybrokerd.exe 和 libunwind.dll 位于同一目录。
4. 检查 Codex 配置语法并重启客户端。

能否在 macOS/Linux 使用？

当前原生实现是 Windows-first，依赖 DPAPI、Named Pipe、WPF 和 Windows OpenSSH Agent。跨平台后端在路线图中，但不能简单复制 Windows 安全假设。

如何报告安全问题？

不要在公开 Issue 中附加真实密钥、Vault、备份或 DPAPI Blob。按照 SECURITY.md 使用合成数据准备报告。