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_ORIGIN=https://your-company.passwd.team npx -y @passwd/passwd-cli@latest 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-cli@latest", "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中创建的密码条目的ID,field默认为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_ORIGIN=https://your-company.passwd.team npx -y @passwd/passwd-agent-cli@latest login创建Skill文件:在OpenClaw的工作空间技能目录下创建文件
~/.openclaw/workspace/skills/passwd/SKILL.md。文件内容需要详细定义Skill的元数据和用法,项目README中提供了一个完整的模板。核心是定义CMD为npx -y @passwd/passwd-agent-cli@latest,并详细说明login、list、exec --inject等命令的交互流程。一个关键的细节是
login流程:因为OAuth是交互式的,Skill文档需要指导AI如何通过exec工具以“进程模式”启动登录,轮询输出以获得OAuth URL,展示给用户,然后等待用户提供重定向URL并通过stdin写入。这个过程确保了登录流程的安全和可控。使用Skill:重启OpenClaw网关后,AI Agent就具备了
passwd技能。当它需要操作数据库时,可以执行:CMD exec --inject DB_PASSWORD=prod-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-cli@latest", "mcp-wrap", "https://internal-api.example.com/mcp", "x-api-key=secret-id-for-api:password", "Authorization=Bearer secret-id-for-token:token" ], "env": { "PASSWD_ORIGIN": "https://company.passwd.team" } } } }原理剖析:
- OpenClaw启动时,会执行上述命令。
passwd-agent-cli mcp-wrap启动,它首先根据PASSWD_ORIGIN和系统密钥链解密获取对应的令牌。- 然后,它解析
x-api-key=...和Authorization=...参数。这些参数格式为HeaderName=SecretID: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-cli@latest 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网关运行的用户和环境,手动执行配置中的命令。例如:
输入一个简单的JSON如PASSWD_ORIGIN=https://... /usr/local/bin/npx -y @passwd/passwd-cli@latest resolve{"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是强大的安全层,但不是银弹,需要与其他安全实践结合使用。