OpenPass:基于age加密与MCP协议的AI原生密码管理器
1. 项目概述:一个为AI时代设计的现代密码管理器
如果你和我一样,日常工作中需要管理几十甚至上百个服务的账号密码,同时又在频繁地与各种AI助手(比如Claude Code、Cursor、Codeium)打交道,那么你肯定也遇到过这样的痛点:每次需要登录某个服务时,要么得手动从1Password或Bitwarden里复制粘贴,要么就得打断AI助手的工作流,自己去找密码。更麻烦的是,当你想让AI助手帮你自动填写表单或者配置某个服务时,由于安全限制,你几乎不可能把密码明文交给它。
OpenPass的出现,就是为了解决这个“最后一公里”的问题。它本质上是一个用Go语言编写的命令行密码管理器,但它的杀手锏在于原生集成了MCP(Model Context Protocol)服务器。这意味着,你的AI助手可以像一个被授权的、安全的“数字管家”一样,在需要时,通过一个受控的、加密的通道,帮你读取甚至管理密码,而无需你手动介入。你不再需要离开编辑器或终端去翻找密码,AI可以直接为你调取。
它的核心设计哲学非常清晰:极简、安全、可编程。它没有花哨的图形界面,所有操作都通过openpass这个命令行工具完成。它用现代加密库age替代了略显陈旧的GPG,使得加密操作更快、更简单。最重要的是,它把密码管理变成了一个可以被其他程序(尤其是AI Agent)安全调用的服务。这不仅仅是“另一个密码管理器”,而是一个面向未来人机协作工作流的密码管理基础设施。
2. 核心设计思路与技术选型解析
2.1 为什么选择 age 而不是 GPG?
传统的Unix密码管理器,比如经典的pass,其基石是GPG(GNU Privacy Guard)。GPG功能强大,但同时也以配置复杂、密钥管理繁琐著称。对于只想安全存个密码的普通用户来说,生成GPG密钥对、管理信任链、处理子密钥等步骤,学习曲线相当陡峭。
OpenPass选择了age(Actually Good Encryption)。这是一个由Filippo Valsorda(Go密码学库的核心维护者)设计的现代加密工具。它的优势在于:
- 极简的API与概念模型:
age的核心概念就是“文件加密和解密”。它使用X25519进行密钥交换,ChaCha20-Poly1305进行认证加密。对用户而言,你只需要一个或多个接收者的公钥(或一个密码),就可以加密文件;用对应的私钥(或密码)就能解密。没有复杂的证书、信任网或过期时间。 - 卓越的性能:
age的加密解密速度极快,尤其是在处理大量小文件时(这正是密码管理器的典型场景),比GPG有显著优势。 - 原生支持密码加密:除了非对称加密,
age也完美支持使用一个强密码(passphrase)进行对称加密。OpenPass正是利用这一点,用你的主密码来加密整个仓库的“身份文件”(identity.age),这个文件里包含了解密所有具体密码条目所需的密钥材料。
从工程角度看,选用age使得OpenPass的代码库更简洁,依赖更少,安全性却因为使用了更现代的密码学原语而可能更高。对于开发者来说,集成age的Go库(filippo.io/age)也比处理GPG的子进程调用要优雅和可靠得多。
2.2 MCP集成:打通AI助手的任督二脉
MCP(Model Context Protocol)是一个新兴的协议,旨在标准化AI助手(模型)与外部工具、数据源之间的通信方式。你可以把它想象成AI世界的“插件系统”或“API网关”。
OpenPass内置MCP服务器,是它区别于所有其他命令行密码管理器的革命性特性。这个设计解决了几个关键问题:
- 安全边界:AI助手运行在沙盒或受限环境中,通常无法直接访问你的密钥环或密码管理器数据库。MCP服务器作为一个本地守护进程运行,持有解密密钥。AI助手通过MCP协议向这个服务器发送经过认证的请求(如“获取
github的密码”),服务器验证权限后,解密数据并返回结果。密码明文永远不会离开OpenPass进程的内存,更不会直接暴露给AI模型。 - 标准化访问:不同的AI助手(Claude Desktop、Cursor、Windsurf等)只要支持MCP,就可以用同一套配置连接OpenPass,无需为每个工具单独开发插件。
- 细粒度权限控制:OpenPass允许你为不同的“Agent”(即AI助手)配置不同的权限。例如,你可以让“Claude Code”拥有对所有密码的读写权,而让一个陌生的实验性AI工具只能读取
work/目录下的密码,且不能修改任何内容。这种基于角色的访问控制(RBAC)在config.yaml中通过agents配置块实现,非常灵活。
2.3 会话缓存与密钥环集成:平衡安全与便利
每次操作都输入主密码无疑是最安全的,但也最令人厌烦。OpenPass在安全与便利之间找到了一个优雅的平衡点:基于操作系统密钥环的会话缓存。
其工作流程如下:
- 当你第一次执行需要密码的操作(如
openpass get)或显式执行openpass unlock时,它会提示你输入主密码。 - 输入正确的主密码后,OpenPass会使用它解密
identity.age文件,获得操作密钥。 - 随后,它会将这个操作密钥(或一个派生出的会话令牌)加密后存储在你操作系统的密钥环中(macOS的Keychain、Linux的Secret Service/libsecret、Windows的Credential Manager)。
- 在接下来的15分钟(默认
sessionTimeout)内,任何OpenPass进程都可以从密钥环中读取这个加密的会话信息,无需再次询问主密码。 - 15分钟后,或你手动执行
openpass lock,缓存将被清除。
实操心得:理解“缓存”的本质这里有一个关键点需要理解:缓存在密钥环里的不是你的主密码明文,而是解密后的、用于实际加密操作的密钥材料。这意味着即使攻击者攻破了你的密钥环,他得到的也是一个加密的Blob,没有主密码依然无法使用。这比缓存主密码本身要安全得多。你可以通过
openpass unlock --ttl 30m来临时调整本次会话的超时时间,比如在进行一段长时间的、需要频繁访问密码的编码工作时。
3. 从零开始:安装与初始化实战
3.1 跨平台安装指南
OpenPass提供了多种安装方式,适应不同用户习惯。
对于绝大多数用户,推荐使用一键安装脚本,它自动处理了下载、校验和安装到系统路径的过程。
# macOS 或 Linux curl -sSfL https://raw.githubusercontent.com/danieljustus/OpenPass/main/scripts/install.sh | sh安装脚本默认会将openpass二进制文件安装到/usr/local/bin(Linux/macOS)或%LOCALAPPDATA%\Programs\OpenPass(Windows)。如果你没有/usr/local/bin的写入权限,或者想安装到自定义目录,可以指定--install-dir参数。
# 安装到当前用户的bin目录,适合没有sudo权限的环境 curl -sSfL https://raw.githubusercontent.com/danieljustus/OpenPass/main/scripts/install.sh | sh -s -- --install-dir ~/.local/bin # 记得将 ~/.local/bin 加入你的PATH环境变量 export PATH="$HOME/.local/bin:$PATH"对于Go开发者,直接使用go install是最简单的,它能自动处理依赖和编译。
go install github.com/danieljustus/OpenPass@latest安装后,二进制文件通常位于$GOPATH/bin或$GOBIN下,请确保该目录已在你的PATH中。
手动安装适用于无法直接联网或需要特定版本的环境。从GitHub Releases页面下载对应你操作系统和架构的预编译二进制文件,解压后放入PATH中的目录即可。
3.2 初始化你的第一个密码仓库
安装完成后,第一步是初始化一个仓库(Vault)。这是存储你所有加密密码的目录。
# 使用默认路径 ~/.openpass openpass init执行这个命令后,你会经历以下交互过程:
- 设置主密码:程序会提示你输入并确认一个强主密码。这是保护你整个密码库的唯一钥匙,务必使用高强度、独一无二的密码。可以考虑使用密码生成器生成一个,并妥善保存在安全的离线位置(如物理笔记本)。
- 生成身份文件:OpenPass会在后台使用
age生成一个加密的身份文件identity.age。这个文件用你的主密码加密,里面包含了解密仓库内具体条目所需的密钥。 - 创建配置:生成基础的
config.yaml配置文件。 - 初始化Git仓库:在仓库目录下初始化一个Git仓库。这是一个非常棒的设计,意味着你所有的密码变更历史都会被自动记录和版本控制。你可以方便地回滚到某个历史版本,或者将仓库同步到私有的Git远程服务器(如GitHub Private、GitLab、Gitea)进行备份和多设备同步。
初始化完成后,你的~/.openpass目录结构大致如下:
~/.openpass/ ├── identity.age # 你的加密身份文件(核心机密) ├── config.yaml # 仓库配置文件 ├── .git/ # Git版本控制目录 └── entries/ # (后续创建)存放具体密码条目的目录注意事项:主密码与备份
- 主密码即一切:如果你忘记了主密码,没有任何方法可以恢复你的密码库。
age加密没有后门。- 立即测试恢复:初始化后,强烈建议你立即添加一个测试密码,然后锁住仓库(
openpass lock),再解锁并读取,确保流程畅通。同时,将整个~/.openpass目录复制到另一个安全的位置(如加密的U盘)作为备份。- Git远程仓库:虽然OpenPass自动初始化了Git,但默认没有设置远程仓库。我建议你尽快添加一个私有远程仓库(
git remote add origin ...),并设置好SSH密钥。这样,openpass git push命令才能生效,实现自动云备份。
4. 日常使用:核心命令详解与最佳实践
4.1 密码的增删改查
添加密码:openpass add命令是交互式的,非常适合快速添加。
openpass add example.com # 随后会交互式地提示输入: # Username (optional): alice@example.com # Password: (输入密码,或直接回车让OpenPass生成一个强密码) # URL (optional): https://example.com/login # Notes (optional): 公司内部系统,密码每90天强制更换。如果你想在脚本中非交互式地添加密码,可以使用openpass set命令:
# 设置密码字段 openpass set example.com.password --value "MyS3cr3tP@ss!" # 设置用户名字段 openpass set example.com.username --value “alice”检索密码:openpass get是最常用的命令。
# 获取整个条目的所有信息 openpass get example.com # 输出: # Path: example.com # Modified: 2023-10-27 10:15 # # password: MyS3cr3tP@ss! # username: alice@example.com # url: https://example.com/login # notes: 公司内部系统,密码每90天强制更换。 # 仅获取密码字段,并直接复制到剪贴板(45秒后自动清除) openpass get example.com.password --clip--clip标志是我最常用的功能之一。它省去了手动选择、复制的步骤,并且自动清除剪贴板的功能极大地减少了密码意外泄露的风险。清除时间可以在config.yaml中通过clipboard.auto_clear_duration配置。
管理与搜索:
# 列出所有条目 openpass list # 列出特定前缀的条目(利用路径层次) openpass list work/ # 在所有字段中搜索关键词 openpass find “aws” # 可能返回 work/aws.root, personal/amazon 等条目 # 编辑条目(会用$EDITOR环境变量指定的编辑器打开解密后的YAML) openpass edit example.com # 删除条目 openpass delete example.com4.2 高级功能:TOTP与密码生成
集成TOTP(时间型一次性密码):这是OpenPass一个非常出彩的功能。你可以将网站的二步验证种子密钥(Secret)直接存储在密码条目中。
openpass add github --totp-secret “JBSWY3DPEHPK3PXP” --totp-issuer “GitHub”添加后,当你获取这个条目时,OpenPass会自动计算并显示当前的6位验证码。
openpass get github # ... 其他字段 ... # totp: 884132 (valid for 24s)你甚至可以通过MCP,让AI助手在需要时帮你获取这个动态码,实现真正的全自动登录。
密码生成器:内置的密码生成器质量很高,免去了寻找外部工具的麻烦。
# 生成一个默认长度(16位)的强密码 openpass generate # 输出类似:xK9#mP2$vL7@nQ4 # 生成一个20位,包含符号的密码,并直接存储到指定条目 openpass generate --store newservice.password --length 20 --symbols # 这条命令会生成密码,并自动执行 `openpass set newservice.password --value <生成的密码>`4.3 多用户仓库与Git同步
管理接收者(多用户):OpenPass支持使用多个age公钥加密仓库,实现团队共享。假设你的同事有一个age公钥age1qy...,你可以将他添加为接收者。
# 列出当前接收者 openpass recipients list # 添加接收者 openpass recipients add age1qy... # 移除接收者 openpass recipients remove age1qy...添加后,新的密码条目将会用所有接收者的公钥(包括你自己的)进行加密。这意味着你和你的同事都可以用各自的私钥解密这些条目。这是一个非常优雅的团队密码共享方案,无需中心化的服务器来分发密钥。
Git操作:OpenPass的所有变更都会自动提交到本地Git仓库。你还可以手动进行同步操作。
# 查看提交历史 openpass git log # 拉取远程变更(如果你设置了远程仓库) openpass git pull # 推送本地变更到远程 openpass git push实操心得:Git冲突处理当多人同时编辑同一个密码仓库并推送时,可能会发生Git冲突。因为密码条目是独立的加密文件,冲突通常发生在
config.yaml或Git的元数据上。解决方法通常是:
- 执行
openpass git pull拉取远程变更。- 如果报告冲突,Git会标记出冲突文件。你需要手动编辑这些文件(如
config.yaml)解决冲突。- 解决后,执行
git add .和git commit完成合并。- OpenPass的自动提交功能只针对密码条目本身的变更,对Git合并冲突的解决需要手动进行。建议团队内约定,修改配置前先沟通。
5. 灵魂所在:为AI助手配置MCP服务器
这是OpenPass最激动人心的部分。下面我将以配置Claude Desktop和Cursor为例,展示如何让AI助手获得安全的密码访问能力。
5.1 配置 Claude Desktop
Claude Desktop 支持通过本地配置文件添加MCP服务器。
生成MCP配置:首先,让OpenPass生成针对
claude-code代理的配置。openpass mcp-config claude-code --http这个命令会输出一段JSON配置。
--http表示使用HTTP模式,服务器会在本地端口(默认8080)监听。相比stdio模式,HTTP模式更稳定,适合作为常驻服务。整合到Claude Desktop配置:
- macOS:配置文件位于
~/Library/Application Support/Claude/claude_desktop_config.json。 - Windows:配置文件位于
%APPDATA%\Claude\claude_desktop_config.json。 - Linux:配置文件位于
~/.config/Claude/claude_desktop_config.json。
如果文件不存在,就创建它。将上一步输出的JSON内容,添加到该文件的
mcpServers对象中。例如:{ “mcpServers”: { “openpass”: { “command”: “openpass”, “args”: [“serve”, “--stdio”, “--agent”, “claude-code”], “env”: {} } } }注意:上面例子是
stdio模式的配置。如果你使用--http模式,配置会有所不同,openpass mcp-config命令输出的JSON已经包含了正确的url和headers(含Bearer Token)。直接复制粘贴即可。- macOS:配置文件位于
启动服务器与验证:保存配置文件后,你需要启动OpenPass的MCP服务器。
# 如果你在配置中使用了HTTP模式,需要手动启动服务器 openpass serve --port 8080 # 服务器将在后台运行,监听127.0.0.1:8080然后,重启Claude Desktop。在Claude的对话窗口中,你现在可以尝试让Claude访问密码。例如,你可以说:“请帮我列出OpenPass里所有的密码条目。” Claude应该能调用
list_entries工具并返回结果。
5.2 配置 Cursor / Windsurf / 其他基于MCP的编辑器
Cursor等现代AI编辑器也支持MCP。配置方式类似,但配置文件的位置和格式可能不同。通常,你需要在编辑器的设置中寻找“MCP Servers”或“AI Tools”配置项。
一个更通用的方法是使用stdio模式,并在编辑器的配置中直接指向openpass命令。
生成stdio配置:
openpass mcp-config codex这个命令会为
codex代理生成配置。codex是OpenPass预置的另一个通用代理配置文件。在Cursor中配置:Cursor的MCP服务器配置通常在一个全局设置文件或工作区设置中。你可能需要编辑类似
~/.cursor/mcp.json的文件,或者通过Cursor的设置UI添加。将生成的配置(包含command和args的部分)添加进去。{ “mcpServers”: { “openpass”: { “command”: “openpass”, “args”: [“serve”, “--stdio”, “--agent”, “codex”] } } }配置完成后,在Cursor的AI聊天框里,你就可以直接说:“获取我
github的密码。” Cursor的AI助手会通过MCP调用OpenPass,并将密码填入聊天框(或者在你同意后自动填入代码中的相应位置)。
5.3 权限管理与安全策略
在~/.openpass/config.yaml中,你可以精细控制每个AI代理的权限。
agents: # Claude Code 拥有全部权限,可以读写任何路径 claude-code: allowedPaths: [“*”] canWrite: true approvalMode: none # Cursor 代理只能读取‘work/’下的条目,且不能写入 cursor-agent: allowedPaths: [“work/”] canWrite: false approvalMode: deny # 一个实验性的新AI工具,访问任何条目都需要我手动批准(在stdio模式下会提示,在HTTP/MCP模式下会降级为拒绝) experimental-ai: allowedPaths: [“*”] canWrite: false approvalMode: promptallowedPaths: 支持前缀匹配。[“work/”, “personal/email”]表示可以访问work/下的所有条目以及personal/email这个特定条目。canWrite: 为false时,该代理无法通过set_entry_field或delete_entry工具修改或删除密码。approvalMode:prompt模式在命令行下会交互式询问你是否批准操作,但在无交互的MCP场景下会安全地降级为deny。
这种设计让你可以放心地授予AI助手权限,因为你知道它们的访问被严格限制在沙盒内。
6. 故障排除与性能调优
即使设计再精良的工具,在实际部署和使用中也会遇到问题。以下是我在深度使用OpenPass过程中总结的常见问题与解决方案。
6.1 常见问题速查表
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
Error: could not open vault: failed to decrypt identity | 1. 主密码错误。 2. identity.age文件损坏。 | 1. 仔细重输主密码,注意大小写。 2. 从备份中恢复 identity.age文件。 |
openpass get命令挂起或无响应 | 1. 会话过期,正在等待输入密码但提示未显示。 2. 与操作系统密钥环通信故障。 | 1. 尝试直接输入主密码后回车。 2. 执行 openpass unlock重新解锁。检查密钥环服务(如Linux的gnome-keyring-daemon)是否运行。 |
AI助手报告Permission denied或Tool not found | 1. MCP服务器未以正确的--agent参数启动。2. 该代理在 config.yaml中权限不足。3. MCP服务器未运行。 | 1. 确保启动命令包含--agent <agent-name>,且<agent-name>在配置中有定义。2. 检查 config.yaml中对应代理的allowedPaths和canWrite设置。3. 运行 openpass serve --stdio --agent default并保持终端打开,或确保HTTP模式服务器在运行。 |
git push/pull失败 | 1. 未设置远程仓库。 2. SSH认证失败。 3. 网络问题。 | 1. 在仓库目录执行git remote add origin <your-git-url>。2. 确认SSH密钥已添加且远程仓库有写入权限。尝试 ssh -T git@github.com测试。3. 检查网络连接。 |
| 剪贴板自动清除功能不工作 | 1. 系统剪贴板管理器冲突。 2. 配置的清除时间为0。 3. 平台不支持。 | 1. 某些Linux桌面环境的剪贴板管理器可能会干扰。尝试禁用或配置其历史记录功能。 2. 检查 config.yaml中的clipboard.auto_clear_duration(单位:秒)。3. 确保你的终端或系统环境支持程序化剪贴板访问。 |
| TOTP代码不匹配 | 1. 系统时间不同步。 2. TOTP种子密钥输入错误。 | 1. 使用ntpdate或系统设置同步时间。2. 使用 openpass edit <entry>检查totp_secret字段是否正确。 |
6.2 性能优化与高级配置
仓库位置与性能:默认的~/.openpass目录在机械硬盘上可能没问题,但如果你将仓库放在SSD上,或甚至放在tmpfs(内存盘)中,openpass命令的响应速度会有显著提升,尤其是openpass list和openpass find这类需要遍历所有加密文件的操作。你可以通过环境变量或--vault参数指定仓库路径。
# 使用环境变量 export OPENPASS_VAULT=/mnt/ssd/.openpass-fast openpass list # 使用命令行参数 openpass --vault /mnt/ssd/.openpass-fast list注意:如果放在tmpfs,重启后数据会丢失,务必配合Git远程仓库实现持久化存储和备份。
会话超时调优:默认的15分钟超时对于安全性和便利性是一个不错的平衡。但在某些场景下你可能需要调整。
- 提高安全性:在公共电脑上,设置为
5m甚至1m。 - 提高便利性:在高度信任的个人电脑上,进行长时间开发时,可以设置为
60m或120m。可以通过openpass unlock --ttl 60m临时设置,或在config.yaml中修改全局的sessionTimeout。
配置Git自动推送:如果你信任网络连接,并希望所有更改自动备份到远程,可以在config.yaml中启用:
git: auto_push: true commit_template: “OpenPass update: %s” # %s会被替换为变更摘要这样,每次你执行openpass add或openpass set后,OpenPass在本地提交后会自动执行git push。
6.3 安全审计与备份策略
定期检查接收者列表:对于团队共享的仓库,定期运行openpass recipients list,确保列表中没有已离职或不应再拥有访问权限的人员。
审查Git历史:虽然Git历史里存储的是加密后的.age文件,但提交记录本身(谁在什么时候提交了)是明文的。定期使用openpass git log --stat查看变更历史,确认没有异常的大量删除或修改操作。
实施“3-2-1”备份策略:
- 3份数据:你的本地仓库是一份。
- 2种介质:除了本地硬盘,将Git远程仓库推送到另一个存储介质,例如另一个云服务商(如同时推送到GitHub和GitLab私有库),或者定期打包加密后上传到冷存储(如加密的S3 Glacier)。
- 1份离线备份:每隔一段时间(如每月),将主密码和
identity.age文件(或整个仓库)加密后,备份到一个完全离线的介质上,如加密的U盘,并物理存放在安全的地方。
密钥环安全:理解你的操作系统密钥环的安全模型。在macOS上,Keychain受用户登录密码保护。在Linux上,确保gnome-keyring或kwallet的解锁密码足够强。OpenPass的会话缓存安全性最终依赖于你的操作系统密钥环的安全性。
