oak-keyring 上手指南:从安装到日常使用

如果你大部分时间都在终端里工作，希望密码库也能自然地待在那里，这篇指南会带你走完从安装到日常使用的完整流程。本文基于当前预览版（v0.8.0-preview.1），部分细节在稳定版发布前可能调整。

你需要准备什么

• 一台 Mac，Apple Silicon 或 Intel 均可。Linux 和 Windows 在形态上很适合这类工具，但预览版目前只支持 macOS。
• 一个你信任的终端模拟器。iTerm2、Kitty、Alacritty、WezTerm、Apple Terminal 都可以。
• 终端里装好 Nerd Font（推荐）。oak-keyring 在侧边栏和列表里用了图标，没有 Nerd Font 的话部分图标会显示成方框或问号，但布局不受影响。

安装

有三种方式，选适合你的就行。

Homebrew

brew tap openkeyring/oak-keyringbrew install ok

npm

npm install -g @openkeyring/okok --version

npm 包内置了 macOS 预编译二进制。如果你的架构暂时没覆盖到，改用 GitHub Release。

GitHub Release

1. 打开 releases 页面。
2. 下载与你的 Mac 架构匹配的 tar 包（Apple Silicon 或 Intel）。
3. 用 checksums.txt 校验文件完整性。
4. 解压后把 ok 二进制移到 PATH 里的目录：

tar xzf ok-*.tar.gzsudomv ok /usr/local/bin/ok --version

预览版二进制未签名、未公证，macOS Gatekeeper 可能拦截首次启动。如果你确认是从官方 GitHub Release 下载且校验过 checksum，可以在「系统设置 > 隐私与安全性」里允许运行，或者执行：

xattr -d com.apple.quarantine /usr/local/bin/ok

创建你的 Vault

启动应用：

ok

首次运行时，oak-keyring 会引导你创建新 vault。需要设置两样东西。

第一项是主密码。每次启动 ok 都要输入它解锁 vault，选一个强且好记的。oak-keyring 不提供托管账户恢复，主密码和恢复词都丢了的话，谁都帮不了你。

第二项是恢复词。oak-keyring 会生成一组 BIP-39 助记词，抄在纸上，存在和电脑分开的安全地方。这是主密码丢失后的最后兜底，重要程度等同于加密货币钱包的种子短语。

设置完成后，你就进入了 TUI 主界面。

界面导览

整个屏幕分成三个区域：

• 左边是侧边栏，在「全部凭证」「安全笔记」「标签」「回收站」之间切换，每项带数量徽标。
• 中间是记录列表，显示当前分类下的记录，包含名称、用户名和时间戳。
• 右边是详情面板，列出选中记录的字段和可用操作。

用 Tab 和 Shift+Tab 在区域之间切换，用 j/k 或方向键在区域内移动。整个界面完全键盘驱动，不需要动鼠标。

创建第一条记录

按 n 新建记录。表单包含标题、用户名、密码、网址、标签和备注等字段。

密码字段可以手动输入，也可以用内置生成器。光标停在密码字段时调用生成器，可以按可配置的长度和字符集生成强密码。

用标签来组织记录（比如 工作、个人、银行）。标签是自由文本，之后可以从侧边栏按标签筛选。

保存后，记录立刻出现在列表里。

搜索和复制

这是最高频的日常操作：找到凭证，复制，粘贴到需要的地方。

按 Ctrl+K 进入搜索模式，输入记录名称的几个字符，列表实时过滤。按 Enter 确认搜索（过滤后的列表保留），或按 Esc 取消搜索恢复之前的列表。

选中记录后，在详情面板里用这些快捷键：

• c 复制密码到剪贴板。
• u 复制用户名。
• p 显示或隐藏密码。

剪贴板内容会在短时间后自动清除，降低粘贴到错误位置的风险。

快捷键参考

在应用里随时按 ? 或 F1 可以查看当前上下文的帮助。

密码生成器

在主界面按 Ctrl+G 可以打开独立的密码生成器。生成前可以配置长度、字符集（大写、小写、数字、符号）和排除规则。

生成器也内嵌在记录表单里。创建或编辑记录需要密码时，可以直接在表单里生成，不需要跳出去。

标签、回收站和恢复

标签显示在侧边栏里，导航到某个标签可以筛选列表。vault 里记录多到搜索不够用时，标签能帮你分层组织。

回收站是软删除。删除记录时，它先进入回收站而不是直接消失，你可以从侧边栏浏览回收站、改主意就恢复。只有你明确清空回收站时，记录才会被永久删除。对一个保管凭证的工具来说，误删可挽回是底线。

导入和导出

oak-keyring 通过 TUI 支持导入和导出。常见场景有两个：从其他密码管理器迁移（从当前工具导出，再导入 oak-keyring），以及创建加密备份（把 vault 导出成文件，加密后存到安全的地方）。

导出文件包含你的凭证明文。请当作高度敏感数据对待，不要放在临时目录、未加密的云盘文件夹或邮件附件里。

可选：Google Drive 同步

在 TUI 里通过 Ctrl+P（设置）配置同步。Google Drive 用作加密传输通道，不是托管 vault。你的 vault 数据在本地加密后才上传到 Google 服务器。

配置好后，在主界面按 Ctrl+R 手动触发同步。

同步是预览功能，默认关闭，完全是可选项。如果你不需要跨设备访问，可以彻底忽略它，保持 vault 纯本地。

自动锁定

Vault 会在一段时间不活动后自动锁定。这防止你离开终端后别人翻看你的凭证。

锁定后需要重新输入主密码解锁。超时时间可以在设置里调整。

密码健康检查

oak-keyring 内置密码健康检查。泄漏密码指示器会标记出现在已知数据泄露中的凭证，省得你手动逐条审查找出需要更新的密码。

实用建议

• 装 Nerd Font。没有它，侧边栏和列表里的图标显示不出来。JetBrains Mono Nerd Font、FiraCode Nerd Font、Hack Nerd Font 都可以。
• 恢复词离线保存。纸质、金属刻字、锁起来的抽屉，别用云笔记、截图或者发给自己的聊天消息。
• 升级前先导出。预览版可能改变数据格式，更新到新预览版之前先导出 vault，万一出问题可以重新导入。
• 保持终端可信。oak-keyring 运行在你的终端里，如果终端会话被入侵，vault 也会受威胁。不要在共享或不受信任的环境里运行 ok。

目前还不支持什么

• Linux 和 Windows 暂不可用，在这些平台上需要再等一等。
• 浏览器自动填充不在产品范围内。oak-keyring 是终端原生的，浏览器登录时需要从 TUI 复制凭证。
• 没有移动端。Google Drive 同步预览是目前的数据通道，但没有移动端客户端来消费它。
• 签名二进制还在路上，目前需要手动校验 checksum。

接下来

• 完整文档：openkeyring.com/zh/docs/
• GitHub：github.com/OpenKeyring/oak-keyring
• Discord：加入社区
• 安全模型：阅读 THREAT_MODEL.md 了解正式的安全假设和边界。

遇到问题可以在 GitHub 提 issue。工作流方面的反馈对项目尤其有用，项目还处于早期，真实使用场景会直接影响优先级。

oak-keyring 不想面面俱到，只想让你不用离开终端就能管理凭证。如果这就是你的工作方式，试试看。