把 LLM 密钥从环境变量里解放出来：OpenClaw.NET 迎来 Vault/OpenBao 密钥后端 - 张善友
内容提要
.NET开发者geffzhang向OpenClaw.NET提交PR #241，新增HashiCorp Vault/OpenBao密钥后端。设计上调用点零改动，原env:OPENAI_API_KEY可直接改写为vault:secret/data/openclaw/openai#api_key。Core层仅加抽象不加依赖，失败路径显式抛异常、拒绝静默降级，密钥值不进日志，启动期校验配置并预热。NativeAOT不含Vault后端，需JIT部署。
延伸解读
零改动迁移的实用价值
PR #241 允许将现有的 env:OPENAI_API_KEY 直接替换为 vault:secret/data/openclaw/openai#api_key，而无需修改任何调用点。这得益于 SecretResolver 静态门面的向后兼容设计：DI 引导后委托给 ISecretResolver，未引导时回退到原有逻辑。对于已部署 OpenClaw.NET 的团队，迁移到 Vault 只需更改配置字符串，大幅降低了重构成本和风险。
故障显式化与安全姿态
该集成拒绝静默降级：所有失败路径都抛出语义化异常（如 VaultAuthException、VaultUnavailableException），且密钥值不会出现在日志或异常消息中。启动期校验配置并预热密钥，预热失败默认阻断启动。这种 fail-closed 策略将故障暴露在早期，避免了运行时因密钥解析失败导致的隐蔽错误，适合对稳定性要求高的生产环境。
NativeAOT 部署的边界
Vault 后端仅包含在 JIT 构建中，NativeAOT 发布物不包含该后端，因为 VaultSharp 不是 trim-safe 的。在 AOT 模式下，vault: 引用会 fail-closed 抛异常。这意味着希望使用 Vault 的团队需要接受 JIT 部署车道，或等待社区提供 trim-safe 的 Vault 客户端。这一限制与 OpenClaw.NET 的 AOT/JIT 能力分巷纪律一致。
企业密钥治理的拼图
对于使用 Nacos 作为 AI 资源控制面、OpenClaw.NET 作为 .NET 数据面的团队，此前 Nacos 凭据常以 env:NACOS_PASSWORD 形式存在环境变量中。现在可改为 vault:secret/data/openclaw/nacos#password，实现密钥集中审计、轮换免重启、节点不持有明文。OpenBao 作为 Vault 的开源分支，为许可证敏感的企业提供了替代选择，PR 的集成测试也基于 OpenBao 容器。
Q&A
OpenClaw.NET 新增的 Vault/OpenBao 密钥后端是什么？
这是 .NET 开发者 geffzhang 向 OpenClaw.NET 提交的 PR #241，为项目增加了 HashiCorp Vault / OpenBao 密钥解析后端。它允许将原本的 env:OPENAI_API_KEY 引用改写为 vault:secret/data/openclaw/openai#api_key，实现密钥集中管理，且所有现存调用点无需改动。
为什么要把密钥从环境变量迁移到 Vault？
环境变量方案存在进程列表可见、容器 inspect 可读、轮换需重启、权限粒度粗等问题。在 AI 平台中，密钥包括按调用计费的模型 API Key、IM 渠道凭据等，泄漏代价更高。Vault 提供集中审计、轮换免重启、细粒度权限，更适合企业多副本、多环境场景。
vault: 引用格式具体怎么写？
语法为 vault:<mount>/data/<path>#<key>。例如标准形态 vault:secret/data/openclaw/openai#api_key，自定义 mount 如 vault:openclaw/data/payments/stripe#sk_live，省略 mount 时默认使用 secret，如 vault:data/config#nested_key。
Vault 后端如何处理失败情况？
所有失败路径都显式抛异常，拒绝静默降级。例如 VaultAuthException、VaultUnavailableException、VaultPathNotFoundException 等。密钥值不会出现在异常消息、日志或追踪中，异常只携带路径、键名、HTTP 状态码和错误类型名。同步解析路径在缓存未命中时直接抛 SecretResolutionException，不会阻塞等待网络。
NativeAOT 构建是否支持 Vault 后端？
不支持。NativeAOT 构建不包含 Vault 后端，因为 VaultSharp 不是 trim-safe 的。在 AOT 发布物中，vault: 引用会 fail-closed 抛异常。只有 JIT 构建才包含该后端，因此想使用 Vault 的团队需要采用 JIT 部署车道。
Vault 后端在启动时做了哪些校验和预热？
启动期会校验配置，如 Enabled=true 时 Address 必须为 HTTPS，TokenRef 必填且不能以 vault: 开头，CacheTtl/RequestTimeout 有范围检查等。同时 VaultRefPrewarmService 会在对外服务前解析 PrewarmRefs 清单并扫描所有 vault: 引用提前拉取，预热失败默认阻断启动。
