【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载导读本文围绕 OpenShell Go SDK 中client.Providers().Refresh()提供的凭据刷新能力系统讲解如何为 Provider Profile 配置自动化的 API 密钥轮换策略、查询刷新状态、手动触发轮换以及删除刷新计划。阅读完成后你将掌握RefreshInterface全部四个操作的调用方式、六种刷新策略的适用场景、失败恢复动作的语义以及底层 gRPC 实现原理能够直接为生产环境中的 AI Provider 接入凭据生命周期管理。Refresh 是什么解决什么问题OpenShell 是面向自主 AI Agent 的安全、私有运行时。AI Agent 调用各家人工智能推理服务时需要使用 API 密钥、OAuth 令牌、云厂商临时凭证等凭据。这些凭据通常有有效期限制——尤其是 OAuth2 access token、云服务临时凭证过期后会导致 Agent 的推理调用中断。OpenShell 的Provider Credential Refresh凭据刷新能力把凭据的“到期轮换”从人工操作变为 gateway 托管的自动化任务自动轮换为 Provider Profile 配置刷新策略后Gateway 会在凭据到期前按计划自动获取新凭据无需人工介入状态监控随时查询每个凭据的最近刷新时间、下次刷新时间、过期时间与失败原因手动接管需要立即换新时可手动触发一次即时轮换Rotate。在 Go SDK 中该功能由client.Providers().Refresh()访问器暴露返回一个实现了 RefreshInterface 的子客户端与 Profiles 一样是ProviderInterface的两个子客户端之一见 Providers 文档 中 Sub-Clients 一节。refreshClient : client.Providers().Refresh()接口总览RefreshInterface 的能力矩阵从 refresh.go 的源码可以看到RefreshInterface定义了四个操作比官方 API 文档中列出的三个方法还多一个Delete用于删除刷新配置文档未展开但在 SDK 与 proto 中均已实现方法签名用途GetStatusGetStatus(ctx, workspace, provider, credentialKey string) ([]*RefreshStatus, error)查询某个 Provider 凭据的刷新状态ConfigureConfigure(ctx, workspace string, config *RefreshConfig) (*RefreshStatus, error)配置/更新自动刷新策略与材料RotateRotate(ctx, workspace, provider, credentialKey string) (*RefreshStatus, error)立即手动触发一次凭据轮换DeleteDelete(ctx, workspace, provider, credentialKey string, opts ...DeleteOptions) (*DeletionResult, error)删除凭据的刷新配置四个操作的参数遵循统一约定workspace工作区名称命名工作区选择器见下文“工作区作用域”providerProvider 类型或名称例如openaicredentialKey该 Provider 下具体凭据的键名例如default。查询刷新状态GetStatusGetStatus用于检查某个具体 Provider 凭据当前的刷新状态返回一个或多个RefreshStatusstatuses, err : client.Providers().Refresh().GetStatus(ctx, default, openai, default) if err ! nil { log.Fatal(err) } for _, s : range statuses { fmt.Printf(Key: %s, Last refresh: %s, Next: %s\n, s.CredentialKey, s.LastRefreshAt, s.NextRefreshAt) }从 types/refresh.go 的源码看RefreshStatus携带的字段远比示例打印的三项丰富足以支撑完整的监控面板与告警逻辑字段类型含义ProviderstringProvider 名称ProviderIDstring服务端分配的 Provider 唯一标识CredentialKeystring凭据键名StrategyRefreshStrategy当前生效的刷新策略Statusstring刷新状态描述ExpiresAttime.Time凭据过期时间NextRefreshAttime.Time下次自动刷新时间零值表示没有安排自动刷新需结合RecoveryAction区分“挂起”与“未设置”LastRefreshAttime.Time最近一次成功刷新时间LastErrorstring最近一次失败的错误信息RecoveryActionRefreshRecoveryAction失败后要求的恢复动作见下文FailureCodestringGateway 托管的稳定失败标识如oauth_invalid_grantProviderErrorSubtypestring有界识别的 Provider 子类型细化FailureCodeLastErrorAttime.Time最近一次失败发生的时间注意NextRefreshAt的语义在 proto 定义中它被明确注释为“缺少即没有安排自动重试”openshell.proto因此不能仅凭“下次刷新时间为零”就判断刷新已正常停止必须配合RecoveryAction判断是需要人工处理还是正常状态。配置自动刷新ConfigureConfigure是核心操作为指定 Provider 凭据设置自动刷新策略与所需材料status, err : client.Providers().Refresh().Configure(ctx, default, v1.RefreshConfig{ Provider: openai, CredentialKey: default, Strategy: v1.RefreshStrategyOAuth2ClientCredentials, Material: map[string]string{ client_id: my-client-id, client_secret: my-client-secret, token_url: https://oauth.example.com/token, }, SecretMaterialKeys: []string{client_secret}, }) if err ! nil { log.Fatal(err) } fmt.Printf(Refresh configured, next rotation: %s\n, status.NextRefreshAt)RefreshConfig的完整字段定义见 types/refresh.go字段类型说明Providerstring目标 ProviderCredentialKeystring目标凭据键名StrategyRefreshStrategy刷新策略必填Materialmap[string]string策略所需的材料如client_id、client_secret、token_url、scopes等SecretMaterialKeys[]string请求以密钥形式存储的材料键名每一项必须已存在于Material中ExpiresAt*time.Time可选显式指定凭据过期时间刷新策略RefreshStrategySDK 导出的策略常量定义于 refresh.go其底层字符串值与 proto 枚举一一对应见 converter/refresh.go常量值适用场景RefreshStrategyStaticStatic静态凭据无需自动刷新默认/回退RefreshStrategyExternalExternal凭据由外部系统提供OpenShell 不负责刷新RefreshStrategyOAuth2RefreshTokenOAuth2RefreshToken使用 OAuth2 refresh token 换取新的 access tokenRefreshStrategyOAuth2ClientCredentialsOAuth2ClientCredentials使用 client_id / client_secret 通过 client credentials 流程获取令牌即上文示例RefreshStrategyGoogleServiceAccountJWTGoogleServiceAccountJWT使用 Google 服务账号 JWT 换取短期访问令牌RefreshStrategyAWSStsAssumeRoleAWSStsAssumeRole通过 AWS STS AssumeRole 获取临时安全凭证后四种策略恰好对应仓库 providers/ 目录中已提供的 Provider Profile 生态如 google-cloud.yaml、aws.yaml、openai.yaml说明刷新能力与 Provider Profile 体系是深度耦合的Profile 定义凭据与默认参数Refresh 负责它们的到期续期。密钥材料的处理proto 层面ConfigureProviderRefreshRequest.material字段被标记为[(openshell.options.v1.secret) true]openshell.proto即整个材料 map 都会被当作敏感信息处理。而secret_material_keys用于显式声明哪些具体键需要以密钥形式存储SecretMaterialKeys中的每个键都必须真实存在于Material中服务端还会结合权威 Provider Profile 与刷新策略自动归类其他密钥。这意味着client_secret这类高敏感字段应以密钥形式落盘而token_url这类非敏感信息可以普通配置存储。幂等与重试request_idConfigureProviderRefreshRequest还支持可选的request_id非零 UUID用于持久化至多一次durable at-most-once准入成功的请求结果可在 24 小时内被重放适合网络不稳定时的安全重试场景openshell.proto。这与仓库 API 错误与重试参考文档docs/reference/api-errors.mdx对应能力的设计保持一致。工作区作用域所有刷新请求都通过namedWorkspaceScope(workspace)构造WorkspaceScope且 proto 注释明确“只接受命名工作区选择”openshell.proto不支持跨全部工作区的全局操作——凭据刷新是强工作区隔离的。手动触发轮换Rotate当凭据疑似泄露、或刷新调度尚未到期但需要立即换新时使用Rotate强制触发一次即时轮换status, err : client.Providers().Refresh().Rotate(ctx, default, openai, default) if err ! nil { log.Fatal(err) } fmt.Printf(Rotated successfully at %s\n, status.LastRefreshAt)Rotate走独立的RotateProviderCredentialRPCopenshell.proto同样支持request_id做至多一次准入openshell.proto。返回的RefreshStatus中LastRefreshAt即为本次轮换的完成时间可用于验证操作是否成功。删除刷新配置DeleteRefreshInterface还提供Delete操作官方 API 文档未展开但 SDK 接口与 proto 均已实现用于移除凭据的自动刷新计划deletion, err : client.Providers().Refresh().Delete(ctx, default, openai, default) if err ! nil { log.Fatal(err) } fmt.Println(Deletion outcome:, deletion.Outcome)Delete支持DeleteOptions中的AllowMissing选项对应 proto 的allow_missing字段openshell.proto当目标刷新配置不存在时返回DELETED而非报错便于实现幂等的清理逻辑。刷新失败与恢复动作RecoveryAction 语义自动刷新失败后仅靠LastError字符串难以机器化处理。OpenShell 为此定义了稳定的恢复动作枚举RefreshRecoveryActiontypes/refresh.go对应 proto openshell.proto枚举值String() 输出含义RefreshRecoveryActionUnspecifiedunspecified无需恢复动作RefreshRecoveryActionRetryretryOpenShell 将自动重试无需人工介入RefreshRecoveryActionReauthorizereauthorizeOAuth 授权已失效必须由用户重新授权RefreshRecoveryActionFixConfigurationfix_configuration配置错误需运维人员修复RefreshRecoveryActionInvestigateinvestigate失败无法归类需要人工排查配合FailureCode如oauth_invalid_grantGateway 托管的稳定标识非 Provider 自由文本与ProviderErrorSubtype监控系统可以实现高度确定性的告警分流例如对reauthorize触发人工介入工单对retry仅记录日志。proto 注释明确建议使用recovery_action而非解析last_error文本来判断失败性质openshell.proto。底层实现gRPC 调用链与转换层SDK 的四个方法与 proto 定义的四个 RPC 一一对应refresh_client.go 与 openshell.protoSDK 方法gRPC RPC请求消息GetStatusGetProviderRefreshStatusGetProviderRefreshStatusRequestConfigureConfigureProviderRefreshConfigureProviderRefreshRequestRotateRotateProviderCredentialRotateProviderCredentialRequestDeleteDeleteProviderRefreshDeleteProviderRefreshRequest调用链如下SDK 方法构造对应 proto 请求填充workspace_scope、provider、credential_key等字段通过 gRPC 调用 Gateway响应中的ProviderCredentialRefreshStatus经 converter/refresh.go 的RefreshStatusFromProto转换为 SDK 层的RefreshStatus枚举、时间戳均在此层完成映射任何错误都经converter.FromGRPCError转换为 SDK 类型化错误供上层err ! nil分支处理。此外proto 中的ProviderCredentialRefresh配置消息还透露了更细的调度参数token_url、scopes、refresh_before提前多少时间刷新、max_lifetime最大生命周期以及additional_outputs一次刷新产出多个凭据时将策略定义的语义输出如session_token映射到兄弟凭据openshell.proto——当前 SDK 的RefreshConfig是这些能力的精简封装更底层的控制可通过原始 proto API 触达。一个值得注意的边界SDK 的 fake 测试客户端fake/refresh.go对四个方法全部返回Unimplemented其注释明确“凭据刷新需要真实服务器”credential refresh requires a real server。也就是说刷新相关的单元测试必须依赖真实 Gateway 或契约测试无法像 Provider 管理那样使用内存 fake 完全离线验证——设计集成测试时需将这一点纳入考量。落地实践建议结合 Providers 文档 与上文内容给出生产环境接入凭据刷新的推荐路径先注册 Provider再配置刷新使用client.Providers().Ensure(...)幂等注册 Provider 与其凭据然后通过Configure绑定刷新策略。Provider Profile 提供的默认参数见 providers/ 下各 YAML可显著减少Material的填写量。敏感字段务必声明为密钥所有口令类材料client_secret、私钥等都要列入SecretMaterialKeys避免明文落库。以 RecoveryAction 驱动告警不要把LastError文本直接写进告警规则改用RecoveryActionFailureCode做确定性分流reauthorize/fix_configuration升级人工retry仅记录。善用 request_id 实现安全重试配置或轮换操作在网络抖动时携带非零 UUID 的request_id可在 24 小时内安全重放避免重复轮换导致凭据错乱。区分“无刷新计划”与“挂起”判断NextRefreshAt为零值时要结合RecoveryActionUnspecified才是正常的无计划状态其余动作值都表示刷新流程需要关注。监控轮换频率定期调用GetStatus汇总各工作区凭据的LastRefreshAt可及早发现 OAuth 授权失效连续reauthorize等群体性故障。关联资源Refresh API 文档本文的原始依据文档Providers API 文档Provider 的注册、更新、Ensure 操作与 Sub-Clients 说明Profiles API 文档Provider 类型 Profile 管理RefreshInterface 定义SDK 接口与策略常量Refresh 类型定义RefreshStatus、RefreshConfig、RefreshRecoveryAction完整字段gRPC 调用实现四个 RPC 的客户端封装proto 服务定义刷新相关的请求/响应消息与 RPC 契约第 368–398、2303–2449、3547–3553 行Provider Profile 定义各 Provider 类型OpenAI、Google Cloud、AWS 等的 Profile 配置赞分享【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载相关推荐OpCore-Simplify终极指南3分钟打造完美黑苹果系统OpCore Simplify终极指南3分钟打造完美黑苹果系统 OpCore Simplify是一款革命性的黑苹果自动化配置工具专为Hackintosh爱好开发工具CLIkOps 集群密钥与凭据轮换实战指南keypair 优雅轮换与 Secret 更新全流程kOps 集群密钥与凭据轮换实战指南keypair 优雅轮换与 Secret 更新全流程 本指南以 kOpsKubernetes Operations中云原生集群管理运维IaC如何用一个开源设备管理平台管住上千台跨平台设备Fleet 实战指南如何用一个开源设备管理平台管住上千台跨平台设备Fleet 实战指南 凌晨两点你在群里被 一台 Linux 开发机被人装上了来路不明的软件一台新员工 M后端前端企业应用运维网络安全上一篇3步快速上手如何为nnUNet医学影像分割开源项目做出高质量贡献下一篇从源码到部署Scratch-www全流程开发指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考