Agent Vault OAuth凭据自动刷新详解GitHub/Google/Slack令牌生命周期管理完全指南【免费下载链接】agent-vaultA HTTP credential proxy and vault for AI agents like Claude Code, OpenClaw, Hermes, custom agents harnesses, and more.项目地址: https://gitcode.com/gh_mirrors/ag/agent-vaultAgent Vault 是一款面向 AI Agent 的 HTTP 凭据代理与保险库Credential Proxy Vault它最被低估的能力之一就是OAuth 凭据自动刷新把 GitHub、Google、Slack 等服务的 OAuth 令牌交给它托管后Access Token 到期前会被透明地自动续期你的 Agent 永远拿不到真实令牌也永远不会因为令牌过期而中断工作。本文带你完整看懂它的令牌生命周期管理机制。为什么 AI Agent 需要 OAuth 令牌生命周期管理传统 API Key 一写管一年但 OAuth 2.0 的 Access Token 天生是短命的GitHub App / OAuth App 的 Access Token 通常只有小时级有效期Google 的 Access Token 有效期仅 1 小时expires_in: 3600Slack、Microsoft 等 likewise令牌过期后必须用 Refresh Token 换新。如果让 Claude Code、OpenClaw、Hermes 这类 Agent 直接持有令牌会遇到两个问题安全令牌躺在 Agent 环境里随时可能被提示词注入Prompt Injection窃取外泄可用性长任务跑到一半令牌过期请求开始批量 401还得人工重新授权。Agent Vault 的思路是Agent 一个令牌都不用碰。所有出站 HTTP 请求强制经过代理代理在转发前把 Bearer Header 换成保险库里最新的有效令牌——过期、刷新、加密存储全在代理内部完成。两种连接方式一键 Connect 或直接粘贴令牌Agent Vault 提供两条 OAuth 凭据接入路径详见官方文档 docs/learn/credentials.mdx 一键 ConnectAuthorization Code PKCE 全自动授权在 OAuth App 平台如 GitHub Settings → Developer Apps注册应用拿到 Client ID / Secret在 Agent Vault 界面填入凭据选择服务商——输入框会智能提示 GitHub、Google、Slack、Microsoft 等热门服务商选中即自动预填授权 URL、Token URL 和认证方式client_secret_post/client_secret_basic点击 Connect浏览器跳转 → 同意授权 → 回调换令牌全程由 Agent Vault 托管并采用PKCE加固授权码流程。内置的服务商预设与推荐 Scopes 定义在 web/src/lib/oauthProviders.ts例如 GitHub 预设会推荐repo、read:user、gist等 scopeSlack 则推荐channels:history、chat:write等新手不用自己查 API 文档。 粘贴令牌从 CLI 工具直接迁移如果令牌已经是现成的比如 Claude Code 本地 OAuth 流程拿到的、IT 部门预置的可以直接粘贴导入。关键设计是一旦你提供了 Refresh TokenAgent Vault 会立刻向服务商的 Token Endpoint 发一次真实刷新来验证验证失败直接拒绝导入——避免把一组已经失效的令牌放进保险库。自动刷新机制详解5分钟缓冲 SingleFlight 去重这是本文的核心。刷新逻辑全部在 internal/brokercore/credential.go 中可以概括为四步第 1 步懒加载判定不做定时轮询Agent Vault 没有后台定时任务。每次代理要注入凭据时才检查该凭据的TokenExpiresAt。如果距过期还有 5 分钟以上常量oauthRefreshBuffer见 internal/brokercore/credential.go#L255直接复用现有令牌零网络开销进入 5 分钟窗口内才触发刷新。第 2 步SingleFlight 并发去重Slack 机器人一秒几十条消息、多个 Agent 同时打 GitHub API 时同一把 Refresh Token 会被多个协程同时需要。Agent Vault 用singleflight保证同一凭据在同一时刻只发一次刷新请求其余请求阻塞等待、共享同一份结果实现见 internal/oauth/refresher.go。这避免了并发刷新导致部分令牌被服务商作废旧的问题。第 3 步标准 refresh_token 授权刷新遵循 RFC 6749 §6由 internal/oauth/oauth.go 的Refresh函数执行携带grant_typerefresh_token、Client 凭证和存储的 Scopes 请求服务商 Token Endpoint。协议层是纯函数式的没有任何数据库和 HTTP Handler 代码可独立测试internal/oauth/oauth_test.go。第 4 步加密回写全链路 AES-256-GCM新 Access Token、可能的新 Refresh Token、新的过期时间全部重新加密后写回数据库迁移脚本 internal/store/048_credential_oauth.go。若刷新失败错误信息会被记录到该凭据上便于你在 UI 里诊断。几个对新手很实用的细节✅令牌无过期时间如某些长期 Access Token或没有 Refresh Token的凭据会被直接跳过不做任何多余请求✅瞬时错误区分408 / 429 被视为可重试的瞬时错误其他 4xx 判定为永久性失败见 internal/oauth/oauth.go#L60-L67✅对 Agent 完全透明服务规则里只引用凭据 key 名Agent 和 Service 根本不知道背后是 OAuth 管理的令牌。实战给 Agent 接上 GitHub / Google / Slack以 GitHub 为例典型配置路径是GitHub 上注册 OAuth App复制 Client ID / Secret在 Agent Vault 新建 OAuth 凭据选择 GitHub 预设勾选repo等所需 scopeConnect 完成授权后在 Service出站规则中把目标api.github.com绑定到该凭据 keyAgent 的所有 GitHub API 请求经代理转发时自动带上永不缺席的新鲜 Bearer Token。GoogleCalendar、Drive、Gmail和 Slack 完全同构只需切换预设——Slack 的 Token Endpoint 等差异项都已预填好。Agent 也可以自己发起 OAuth 凭据提案Proposal 中声明type: oauth由管理员审批后生效全程不接触令牌值参考 docs/learn/credentials.mdx#L129-L152。相关源码与文档导航 模块说明internal/oauth/oauth.go授权码交换与 refresh_token 刷新协议实现internal/oauth/pkce.goPKCE Code Verifier / Challenge 生成internal/oauth/refresher.goSingleFlight 刷新去重器internal/brokercore/credential.go#L255-L3365 分钟缓冲窗口与刷新编排逻辑web/src/lib/oauthProviders.tsGitHub/Google/Slack 等服务商预设docs/learn/credentials.mdx官方 OAuth 凭据使用文档总结Agent Vault 把 OAuth 令牌生命周期管理做成了对 Agent 完全透明的一件事接入一键 ConnectPKCE 授权码流程或粘贴令牌导入即验证刷新请求触发 5 分钟缓冲窗口singleflight 保证并发下只刷新一次安全令牌全程 AES-256-GCM 加密存储Agent 与 Service 均不感知真实值。对于要长时间跑任务的 AI Agent 来说这意味着告别跑一半 401的尴尬也彻底堵住了令牌被注入攻击外泄的通道。想要深入体验可以从 docs/guides/oauth-claude-code.mdx 和 README.md 开始上手。【免费下载链接】agent-vaultA HTTP credential proxy and vault for AI agents like Claude Code, OpenClaw, Hermes, custom agents harnesses, and more.项目地址: https://gitcode.com/gh_mirrors/ag/agent-vault创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考