1. 项目概述为AI Agent设计的“看不见”的密码管理器在AI Agent智能体日益深入我们工作流的今天一个核心的安全挑战浮出水面如何让AI助手比如Claude、GPTs安全地使用我们的数据库密码、API密钥、TOTP动态令牌同时又确保这些敏感信息永远不会暴露在AI的“眼前”传统的做法要么是把明文密钥硬编码在提示词里极其危险要么是让AI直接调用一个能吐出明文的密码管理器API同样危险。这就像把家里的钥匙交给一个聪明的管家却无法阻止他偷偷看一眼钥匙的形状并复制一把。我最近深度使用并研究了pepuscz/passwd这个开源项目它精准地解决了这个痛点。简单来说它是一个专为AI Agent设计的密码管理器客户端套件其核心哲学是**“使用而不看见”**。你的AI助手可以通过它获取凭证、执行需要认证的命令如连接数据库、调用私有API但所有命令的输出都会被实时“打码”原始密码值永远不会进入AI的上下文或返回给用户界面。这对于在Claude Desktop、OpenClaw等环境中安全地集成各类服务至关重要。这个项目提供了四种不同“权限等级”的工具适配从严格的AI协作者到完全受控的脚本环境Claude扩展最严格完全在Claude应用内运行AI只能请求操作看不到任何原始值。MCP服务器提供只读的凭证浏览和TOTP生成能力适合任何支持MCP协议的客户端。Agent CLI核心工具允许AI通过命令行安全地执行注入凭证的命令。Full CLI功能完整的命令行工具供开发者或脚本在受控环境中使用。接下来我将拆解这套工具的设计思路、具体如何部署集成并分享在实际使用中积累的配置技巧和避坑经验。2. 核心架构与安全设计解析在深入实操之前理解passwd的设计哲学和架构是关键。这能帮你判断它是否适合你的场景以及如何以最安全的方式使用它。2.1 “使用而不看见”的安全模型传统密码管理器如1Password、Bitwarden的核心交互是“查询-返回明文”。用户或脚本请求一个密码管理器验证身份后返回明文。这对于人类操作是可行的但对于AI Agent明文一旦进入其上下文就存在被意外记录、泄露或在后续对话中被引用的风险。passwd引入了一个关键抽象凭证注入与输出掩码。它的工作流程更像是请求AI发出指令如“用数据库凭证运行一个查询”。解析与注入passwd工具解析指令从本地的、加密的令牌存储中获取真正的凭证并将其作为环境变量注入到一个全新的子进程如psql,curl中。执行与掩码子进程执行其stdout和stderr被实时监控。任何看起来像密码、令牌的字符串都会被自动替换为concealed by passwd。返回被“打码”后的安全输出返回给AI。AI知道操作成功了看到了查询结果但从未接触过原始密码。这个模型将AI的角色从“凭证持有者”转变为“操作指令发出者”而passwd则扮演了可信的、自动化的执行中介。2.2 工具链的权限梯度与选型指南项目提供的四个工具构成了一个清晰的权限边界你需要根据“谁在执行操作”和“环境是否受控”来做出选择。Claude扩展 (.mcpb文件)能力在Claude Desktop应用内直接使用。AI可以浏览条目看到标题、类型但密码字段显示为***、获取TOTP、并让passwd代表它执行命令输出被掩码。限制绝对无法输出原始凭证也无法执行创建、更新、删除等写操作。适用场景普通用户与Claude日常协作需要安全地登录网站用TOTP、查询数据库或调用内部API。这是最安全、最便捷的AI集成方式。MCP服务器能力一个标准的MCP服务器提供list_secrets,get_secret凭证字段被脱敏,get_totp_code等只读工具。限制纯只读无凭证注入功能。适用场景为任何支持MCP的AI客户端如Cursor、Windsurf提供只读的密码库访问能力。通常需要配合Agent CLI的exec功能来完成需要凭证的实际操作。Agent CLI (passwd-agent-cli)能力这是安全自动化核心。具备浏览、TOTP功能最关键的是exec --inject命令可以安全地将凭证注入子进程。所有命令的输出都经过强制掩码没有获取原始值的选项。限制无法直接输出密码明文无法执行密码库的写操作增删改。适用场景任何AI Agent拥有Shell访问权限的环境。例如在Claude Code、Cursor的Agent模式中AI可以安全地调用这个CLI来运行部署脚本、数据库迁移等。它也是OpenClaw“Agent Skill”的底层实现。Full CLI (passwd-cli)能力功能完整的命令行客户端包含所有CRUD操作创建、读取、更新、删除、分享并且可以通过--field参数输出凭证明文通过--no-masking关闭输出掩码。限制过于强大如果被AI直接调用会导致凭证泄露。适用场景仅限于完全由人类控制的终端、自动化脚本CI/CD或作为OpenClaw的“Secrets Provider”在网关启动时静态拉取配置。严禁在AI可访问的上下文中直接使用。核心安全准则永远只为AI Agent配置和使用Agent CLI或更高权限限制的工具MCP Server, Claude扩展。Full CLI只应出现在后端配置或基础设施代码中。2.3 认证与令牌存储机制所有工具都通过Google OAuth 2.0与你的passwd.team服务器认证。首次使用时会打开浏览器完成登录。之后刷新令牌Refresh Token会被加密存储在本地。加密存储令牌使用AES-256-GCM加密。加密密钥不存储在磁盘上而是保存在操作系统的密钥管理系统中。macOS使用Keychain。Linux使用libsecret通常通过secret-tool命令访问。令牌发现工具会从当前工作目录开始向上递归查找.passwd目录来寻找令牌文件类似.git也支持全局的~/.passwd目录。这实现了灵活的“每项目”或“全局”身份管理。这种设计意味着即使项目文件被泄露没有对应的系统密钥链攻击者也无法解密令牌。同时“每项目令牌”特性非常适合团队协作每个Git仓库可以关联到不同的passwd.team工作区。3. 详细配置与集成实战理解了架构我们来一步步实现集成。我将以最常见的两个场景为例在Claude Desktop中日常使用以及在OpenClaw中构建安全的AI Agent工作流。3.1 集成到Claude Desktop最快捷的安全协作这是体验“使用而不看见”最直接的方式。1. 下载与安装前往项目的GitHub Releases页面下载最新的passwd.mcpb文件。这是一个Claude扩展包。在macOS上通常双击该文件即可自动启动Claude并完成安装。如果不行可以手动打开Claude Desktop进入Settings-Developer-Install MCP Server from file...选择该.mcpb文件。2. 基础配置安装后Claude会提示你配置PASSWD_ORIGIN环境变量。这里需要填入你的passwd.team部署地址。如果你在使用官方的app.passwd.team可以保持默认。如果是自托管或团队服务器则填入对应的URL例如https://vault.your-company.com。3. 认证与使用配置好后直接在Claude的聊天窗口中告诉它“请帮我登录passwd”。Claude会调用passwd_login工具你的默认浏览器会弹出引导你完成Google OAuth授权。成功后Claude即获得了一个安全的凭证访问通道。实操示例安全连接数据库假设你的passwd.team里存了一个PostgreSQL数据库的密码条目ID是prod-db-password。你可以对Claude说“查找我名为‘prod-db’的数据库密码条目。”Claude会调用list_secrets或get_secret工具返回该条目的信息用户名、主机等密码显示为***。接着你说“现在连接到这个数据库列出所有的表。”Claude会使用run_with_credentials工具。这个工具内部会做以下几件事从本地存储解密并获取prod-db-password对应的真实密码。启动一个psql子进程将密码通过环境变量如PGPASSWORD注入。执行psql -h host -U user -c \dt。将psql的输出进行掩码处理将任何可能暴露密码的文本替换掉。将安全的输出结果返回给Claude并展示给你。整个过程中Claude和你的聊天界面里都看不到真实的密码。这种“两段式”对话先定位凭证再执行操作是目前最流畅的使用模式。3.2 集成到OpenClaw构建企业级AI网关OpenClaw是一个功能强大的AI Agent网关和编排框架。passwd为其提供了两种互补的集成方式分别解决“静态配置”和“动态运行时”的凭证需求。场景一Secrets Provider网关启动时注入这个集成用于解决模型提供商API密钥等静态配置的保密问题。凭证在OpenClaw网关启动时被解析并加载到内存中AI Agent完全接触不到。操作步骤网关认证首先你需要以网关的身份而非Agent身份进行认证。在终端执行PASSWD_ORIGINhttps://your-company.passwd.team npx -y passwd/passwd-clilatest login注意这里使用的是passwd-cli全功能CLI因为网关是一个受你完全控制的后台进程。修改OpenClaw网关配置编辑OpenClaw的配置文件通常位于~/.openclaw/openclaw.json在secrets.providers部分添加passwd提供者。{ secrets: { providers: { passwd: { source: exec, command: /usr/local/bin/npx, args: [-y, passwd/passwd-clilatest, resolve], passEnv: [PASSWD_ORIGIN, HOME], allowSymlinkCommand: true, trustedDirs: [/usr/local, /opt/homebrew] } } } }command必须使用npx的绝对路径。你可以通过which npx命令找到它。allowSymlinkCommand在macOS通过Homebrew安装Node.js时npx可能是一个软链接需要将此设为true。trustedDirs出于安全考虑需要声明npx所在目录为可信目录。引用密钥现在你可以在配置模型的API密钥时使用SecretRef来引用passwd中的条目了。{ models: { providers: { openai: { baseUrl: https://api.openai.com/v1, apiKey: { source: exec, provider: passwd, id: your-openai-key-id:password } } } } }id的格式是SECRET_ID:field。SECRET_ID是你在passwd.team中创建的密码条目的IDfield默认为password。如果你的条目有其他字段如api_key可以指定SECRET_ID:api_key。重要限制OpenClaw的SecretRef目前仅支持特定的配置字段如模型API密钥。对于数据库连接字符串、部署密钥等需要在Agent运行时动态使用的凭证此方法不适用。这就需要用到下面的Agent Skill。场景二Agent Skill运行时动态使用Agent Skill允许AI Agent在运行时安全地访问密码库、生成TOTP并将凭证注入到它发起的命令中。操作步骤Agent认证这里必须使用passwd-agent-cli它是专门为AI环境设计的“安全阉割版”。PASSWD_ORIGINhttps://your-company.passwd.team npx -y passwd/passwd-agent-clilatest login创建Skill文件在OpenClaw的工作空间技能目录下创建文件~/.openclaw/workspace/skills/passwd/SKILL.md。文件内容需要详细定义Skill的元数据和用法项目README中提供了一个完整的模板。核心是定义CMD为npx -y passwd/passwd-agent-clilatest并详细说明login、list、exec --inject等命令的交互流程。一个关键的细节是login流程因为OAuth是交互式的Skill文档需要指导AI如何通过exec工具以“进程模式”启动登录轮询输出以获得OAuth URL展示给用户然后等待用户提供重定向URL并通过stdin写入。这个过程确保了登录流程的安全和可控。使用Skill重启OpenClaw网关后AI Agent就具备了passwd技能。当它需要操作数据库时可以执行CMD exec --inject DB_PASSWORDprod-db-id:password -- psql -h db.host.com -U app_user -c SELECT * FROM users;AI只会看到被掩码后的查询结果而真实的DB_PASSWORD环境变量只在psql子进程的生命周期内存在。多环境管理技巧如果你需要同时连接公司company.passwd.team和个人app.passwd.team两个密码库可以分别用不同的PASSWD_ORIGIN环境变量执行login。登录后AI在调用Skill时可以通过--env标志指定环境例如CMD list --env company。passwd工具会根据环境名称的子字符串如“company”自动匹配对应的令牌。4. 高级用法与核心原理深潜掌握了基本集成后我们来看看一些高级场景和其背后的工作原理这能帮助你在更复杂的环境中游刃有余。4.1 通过mcp-wrap安全连接私有MCP服务这是一个非常强大的特性。假设你有一个内部服务的MCP服务器需要API密钥认证。你既不想把密钥硬编码在MCP配置里也不想让AI看到它。mcp-wrap就是解决方案。传统的不安全配置{ mcpServers: { my-service: { command: npx, args: [-y, mcp-remote, https://internal-api.example.com/mcp], env: { API_KEY: sk-live-xxxxxxx // 密钥明文暴露 } } } }使用passwd的安全配置{ mcpServers: { my-service: { command: npx, args: [ -y, passwd/passwd-agent-clilatest, mcp-wrap, https://internal-api.example.com/mcp, x-api-keysecret-id-for-api:password, AuthorizationBearer secret-id-for-token:token ], env: { PASSWD_ORIGIN: https://company.passwd.team } } } }原理剖析OpenClaw启动时会执行上述命令。passwd-agent-cli mcp-wrap启动它首先根据PASSWD_ORIGIN和系统密钥链解密获取对应的令牌。然后它解析x-api-key...和Authorization...参数。这些参数格式为HeaderNameSecretID:Field。mcp-wrap从passwd.team服务端获取secret-id-for-api条目中password字段的真实值以及secret-id-for-token条目中token字段的真实值。最后它启动真正的mcp-remote进程并将获取到的值作为HTTP请求头x-api-key: value,Authorization: Bearer value传递给该进程。mcp-remote与远程MCP服务器的所有通信都会经过passwd-agent-cli的代理输出会被掩码。这样敏感的API密钥只存在于passwd.team服务器和本地加密存储中永远不会出现在配置文件或AI的上下文中。4.2 输出掩码Masking机制详解这是passwd安全性的基石。它不仅仅是简单地在返回前替换字符串而是一个在子进程stdout/stderr流上的实时过滤器。工作原理模式匹配当使用exec或run_with_credentials时passwd会从passwd.team服务端获取本次注入的所有凭证的原始值。流式处理它启动目标命令的子进程并创建管道pipe连接到子进程的stdout和stderr。实时扫描子进程输出的数据流会经过passwd的扫描器。扫描器会查找数据流中是否包含任何与已知凭证值完全匹配的字符串。动态替换一旦发现匹配立即将该字符串替换为占位符concealed by passwd。这个替换是字节级别的确保即使密码被部分输出或与其他文本混合也能被正确识别和掩码。转发结果处理后的“安全”数据流被转发给调用方如AI Agent。注意事项与局限仅完全匹配掩码只对完整的凭证值有效。如果密码是abc123而程序输出的是abc123def则不会被掩码。因此确保应用程序不会以拼接、编码如Base64或哈希形式泄露密码至关重要。性能开销对于输出量巨大的命令如cat一个大文件实时扫描会带来轻微开销。但在数据库查询、API调用等典型场景中开销可忽略不计。无法防止间接泄露如果命令的输出是“登录成功”或一个包含敏感信息非密码本身的JSON对象掩码机制无法识别。安全最终依赖于被调用命令本身的行为。4.3 项目结构与源码构建对于想要贡献或深度定制的开发者了解项目结构很有帮助。它是一个Monorepo使用npm workspace管理。packages/ passwd-lib/ # 核心库。包含所有类型定义、认证逻辑、API客户端。关键点是零依赖zero-dependency最大化可移植性和安全性。 passwd-mcp/ # MCP服务器实现。依赖passwd-lib提供标准MCP工具。 passwd-mcpb/ # Claude扩展包生成器。将MCP服务器打包为.mcpb格式。 passwd-cli/ # 全功能命令行工具。依赖passwd-lib。 passwd-agent-cli/ # 代理CLI。同样依赖passwd-lib但通过移除--field和--no-masking等选项的代码在编译层面确保安全。从源码构建git clone https://github.com/pepuscz/passwd.git cd passwd npm install # 安装所有workspace的依赖 npm run build # 编译所有TypeScript包构建后你可以直接运行编译后的JS文件例如用node packages/passwd-agent-cli/dist/index.js login代替npx passwd/passwd-agent-clilatest login。这在需要固定版本或网络受限的环境中很有用。5. 常见问题、故障排查与实战心得在实际部署和使用中你可能会遇到一些问题。以下是我总结的常见故障点及其解决方案。5.1 认证与登录问题问题登录时浏览器页面显示错误如redirect_uri_mismatch。原因这通常发生在自托管passwd.team服务器时Google OAuth客户端配置不正确。passwd客户端会从PASSWD_ORIGIN指向的服务器动态发现OAuth配置。如果服务器配置的“已授权的JavaScript来源”和“已授权的重定向URI”不包含客户端使用的地址就会报错。解决检查你的passwd.team服务器配置。确保OAuth客户端设置中包含了你的客户端实际使用的域名和正确的重定向URI路径通常是/auth/callback。问题在Linux服务器上Agent Skill或CLI报错提示无法访问密钥环。原因passwd依赖libsecret来安全存储令牌。如果OpenClaw网关或AI Agent进程不是在图形桌面环境或一个配置了DBUS_SESSION_BUS_ADDRESS的上下文中运行它可能无法连接到用户的密钥环服务。解决确保已安装libsecret和libsecret-tools例如在Ubuntu上sudo apt-get install libsecret-1-0 libsecret-tools。对于systemd用户服务需要确保服务能访问到DBUS_SESSION_BUS_ADDRESS。一个可靠的方法是在启动OpenClaw网关前在shell中执行eval $(dbus-launch --sh-syntax)来设置环境变量然后再启动网关。更简单的方法是使用“每项目令牌”功能通过passwd login .将令牌以加密形式存储在项目目录的.passwd文件夹中。这样就不完全依赖系统密钥环但需确保该目录的安全例如通过.gitignore忽略。5.2 OpenClaw集成故障问题OpenClaw网关启动失败日志显示passwdsecrets provider执行错误。排查步骤检查命令路径确认openclaw.json中command字段的npx绝对路径是否正确。使用which npx确认。手动测试命令在终端中切换到OpenClaw网关运行的用户和环境手动执行配置中的命令。例如PASSWD_ORIGINhttps://... /usr/local/bin/npx -y passwd/passwd-clilatest resolve输入一个简单的JSON如{id: test:password}到stdin看是否能正确返回解析结果或错误信息。这能隔离是配置问题还是认证问题。检查令牌确保已用正确的PASSWD_ORIGIN为网关执行过passwd-cli login。令牌应存储在~/.passwd或网关进程有权限访问的目录下的.passwd中。问题AI Agent无法使用passwd技能提示“command not found”或权限错误。原因Skill中定义的CMD依赖于npx。如果AI Agent进程的PATH环境变量与你的用户shell不同可能找不到npx。解决在Skill文件(SKILL.md)的metadata部分可以通过requires.bins声明依赖但这只做检查。更稳妥的方法是在启动OpenClaw Agent的环境或systemd服务文件中显式设置PATH环境变量使其包含Node.js和npx的路径。5.3 安全策略与最佳实践严格区分CLI用途牢记passwd-cli全功能和passwd-agent-cli代理专用的界限。在任何一个AI可触达的自动化脚本、技能或配置中只使用passwd-agent-cli。将passwd-cli的使用严格限制在终端手动操作和CI/CD流水线的受信环节。利用“每项目令牌”进行隔离在团队项目中强烈推荐在项目根目录执行passwd login .。这会在项目下创建.passwd文件夹存储加密令牌。好处是项目隔离每个项目可以关联到不同的passwd.team工作区。权限隔离项目协作者只需要访问该项目的密码库而非你的全部密码。便于清理删除项目文件夹即移除了相关令牌。谨慎处理stdin输入当通过echo password | passwd create ...方式从管道创建密码时确保管道来源安全并且密码不会留在shell历史记录中。对于高度敏感的凭证更推荐使用交互式输入。定期审计与更新关注项目的GitHub Releases页面。安全工具更新频繁及时更新CLI版本和扩展文件。在更新OpenClaw等集成的配置时注意版本号的变化并充分测试。理解安全边界passwd极大地降低了AI泄露明文密码的风险但它不解决所有问题。例如AI仍然可能通过注入的凭证执行破坏性操作如DROP DATABASE。因此分配给AI Agent的密码库访问权限应遵循最小权限原则并且对应的服务账户如数据库用户本身也应具有严格限制的权限。passwd是强大的安全层但不是银弹需要与其他安全实践结合使用。