核心用法
Keychain Bridge 是专为 macOS 设计的密钥管理工具，解决明文存储凭证的安全隐患。其核心采用双组架构：Group A 直接通过 Python keyring 库读写 Keychain，适用于纯 Python 场景；Group B 则在系统启动时将 Keychain 中的密钥写入 chmod 600 的临时文件，供 Bash 脚本读取，解决 Bash 子进程调用 Python 时因 SecurityAgent 会话丢失导致的挂起问题。
工具提供完整的密钥生命周期管理：批量迁移脚本自动检测系统所有 Python 版本并注入 ACL 条目；审计脚本扫描明文泄露与 ACL 配置异常；健康检查验证读写删闭环。特别针对 macOS Tahoe 26.x 的 security CLI 全面失效（hang 或 exit 36）、SSH 会话无 GUI 上下文（errSecInteractionNotAllowed -25308）等回归缺陷，提供了基于 ctypes 直接调用 Security Framework C API 的解锁方案，并明确标注了各 Python 版本间的 ACL 隔离限制。
显著优点
1. 深度适配最新 macOS：针对 Tahoe 26.x 的 security CLI 崩溃、LaunchAgent 子进程挂起等已知问题提供详尽诊断与绕过方案
2. 多 Python 版本兼容：自动处理 Apple 系统 Python 与 Homebrew Python 的 ACL 隔离，确保跨版本可访问
3. 零网络依赖：完全本地操作，无外部 API、无遥测、无数据出境
4. 迁移友好：支持 --dry-run 预演，自动验证 round-trip 读回，可选删除原明文文件
5. 架构清晰：Group A/B 设计明确区分使用场景，兼顾安全性与 Bash 生态兼容
潜在缺点与局限
- Tahoe 26.x 特有复杂性：SSH 写入需 ctypes 解锁，且解锁作用域仅限单进程；Homebrew Python 在 ctypes 解锁后仍可能失败，必须使用系统 Python 写入后注入
- Bash 直接调用限制：
python3 get_secret.py从 LaunchAgent 的 bash 脚本中调用会无限挂起，必须依赖 Group B 文件桥接 - 密钥轮换成本：多 Python 版本环境需为每个版本安装
keyring并注入 ACL，维护成本随 Python 版本数线性增长 - GUI 上下文依赖：除文件桥接外，多数操作需要图形会话（SecurityAgent），纯 SSH 环境受限
适合人群
- 运行 macOS Tahoe 26.x 且依赖 API 密钥自动化脚本的开发者
- 使用 OpenClaw 或其他自动化框架、需将明文密钥迁移至 Keychain 的运维人员
- 多 Python 版本共存（系统 + Homebrew）环境的 macOS 用户
- 对密钥安全有硬性合规要求、需消除明文存储的个人或小团队
常规风险
| 风险类型 | 说明 |
|---------|------|
| ACL 配置遗漏 | 未从所有目标 Python 版本注入，导致后续读取失败 |
| ctypes 解锁误用 | 误以为解锁持久化，跨进程调用仍报 -25308 |
| 文件桥接权限漂移 | Group B 的 `chmod 600` 文件若被其他进程修改权限，可能意外暴露 |
| 系统升级回归 | macOS 后续版本可能再次破坏 `keyring` 或 Security Framework 行为 |
| 密码输入泄露 | ctypes 解锁示例代码中的明文密码可能残留于 shell history |