keepassxc教程

keepassxc教程

Termux下的keepassxc-cli（2.7.12版本）有bug，不好用，多个名称相同的条目只会得到第1个，无法得到的指定的。因此使用 pykeepass（pip安装） 来代替。

电脑端官网：https://keepassxc.org/download

安卓端官网：https://github.com/PhilippC/keepass2android/releases/latest

电脑端与安卓端都是使用 kdbx 数据库文件。

浏览器扩展生效前提是本地已经安装并创建了密码数据库（kdbx）文件，在 设置 中 启用浏览器集成，开启需求的 浏览器集成。

kp.py — KeePassXC KDBX 命令行读取工具

简介

kp.py 是一个轻量读取脚本，用于从 KeePassXC 的 kdbx 数据库读取账号密码。 核心目的：避开 keepassxc-cli 各版本存在的各类命令行bug，不替代 KeePassXC GUI。

整套工作流：

  • Windows：KeePassXC GUI 管理密码 + KeePassXC-Browser 浏览器扩展实现网页自动填充
  • 同步：Syncthing P2P 同步 password.kdbx 到 Termux / WSL / Android KeePassDX
  • Termux/WSL：kp.py 读取 kdbx，提取 API 密钥并导入 shell 环境变量，供 OpenCode、Hermes 等程序使用

功能特性

  • 关键词搜索模式：按标题 / URL 模糊检索条目，列出序号、UUID、用户名、标题、链接；交互式选择输出密码，适合手动查找并获取 UUID。
  • UUID 直接查询模式：传入 UUID，遍历条目匹配，直接输出密码到 stdout，用于自动化 shell 脚本捕获环境变量。
  • 兼容旧版 pykeepass：手动遍历比对 UUID 字符串，规避旧版 find_entries_by_uuid API 报错问题。
  • 安全密码输入：使用 getpass，终端不回显主密码。
  • 仅只读：本脚本只读取，不支持新增/修改/删除 kdbx 内密码；密码维护仍然使用 KeePassXC GUI.

依赖安装

Termux
1
2

pkg install python
pip install pykeepass
WSL / Ubuntu Linux
1
2

sudo apt install python3 python3-pip
pip3 install pykeepass

文件清单

  • kp.py：主Python读取脚本
  • load_ai_secrets.sh：Shell 批量加载密钥模板
  • readme.org：本文档
  • prompt.org：AI维护脚本的提示词文档
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

#!/usr/bin/env python3
from pykeepass import PyKeePass
import getpass
import sys

def search_entries(db_path, keyword, keyfile=None):
    master_pw = getpass.getpass("Enter KeePassXC master password: ")
    kp = PyKeePass(db_path, password=master_pw, keyfile=keyfile)
    results = []
    for entry in kp.entries:
        if keyword.lower() in entry.title.lower() or (entry.url and keyword.lower() in entry.url.lower()):
            results.append(entry)
    if len(results) == 0:
        print("No matching entries found.", file=sys.stderr)
        sys.exit(1)
    for idx, e in enumerate(results):
        print(f"[{idx}] UUID:{e.uuid} | Title:{e.title} | User:{e.username} | URL:{e.url}")
    print("\nEnter number to get password:", file=sys.stderr)
    sel_idx = input("> ")
    try:
        sel = results[int(sel_idx)]
        print(sel.password)
    except Exception as err:
        print(f"Invalid selection: {err}", file=sys.stderr)
        sys.exit(1)

def get_by_uuid_safe(db_path, target_uuid, keyfile=None):
    master_pw = getpass.getpass("Enter KeePassXC master password: ")
    kp = PyKeePass(db_path, password=master_pw, keyfile=keyfile)
    for entry in kp.entries:
        if str(entry.uuid).lower() == target_uuid.lower():
            print(entry.password)
            return
    print(f"UUID {target_uuid} not found", file=sys.stderr)
    sys.exit(1)

if __name__ == "__main__":
    if len(sys.argv) <3:
        print("Usage:", file=sys.stderr)
        print("  python3 kp.py db.kdbx search google.com", file=sys.stderr)
        print("  python3 kp.py db.kdbx get  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", file=sys.stderr)
        sys.exit(1)
    db = sys.argv[1]
    mode = sys.argv[2]
    arg = sys.argv[3]
    kf = sys.argv[4] if len(sys.argv)>=5 else None
    if mode == "search":
        search_entries(db, arg, kf)
    elif mode == "get":
        get_by_uuid_safe(db, arg, kf)
    else:
        print("mode must be search / get", file=sys.stderr)
        sys.exit(1)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

#!/bin/bash
DB="$HOME/keepassxc/password.kdbx"

# 示例密钥，替换为你自己的UUID
GMAIL_PASS=$(python3 kp.py "$DB" get "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")
ANTHROPIC_API_KEY=$(python3 kp.py "$DB" get "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")
DEEPSEEK_API_KEY=$(python3 kp.py "$DB" get "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")

export GMAIL_PASS
export ANTHROPIC_API_KEY
export DEEPSEEK_API_KEY

echo "✅ 密钥加载完成"

使用方法

搜索模式（不知道UUID，交互式查询，手动查找账号）

语法：

1

python3 kp.py /path/to/password.kdbx search "keyword"

示例：

1

python3 kp.py ~/keepassxc/password.kdbx search "google.com"

执行流程：

  1. 输入 KeePassXC 数据库主密码（无回显）
  2. 打印所有匹配条目：[序号] UUID | Title | User | URL
  3. 输入条目序号，脚本输出对应密码。
UUID 查询模式（自动化脚本，预先拿到UUID）

语法：

1

python3 kp.py /path/to/password.kdbx get "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

示例，用于shell捕获变量：

1
2
3

GMAIL_PASS=$(python3 kp.py ~/keepassxc/password.kdbx get "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")
export GMAIL_PASS
echo $GMAIL_PASS
批量加载密钥脚本执行
1
2

chmod +x load_ai_secrets.sh
source ./load_ai_secrets.sh

重要限制 & 注意事项

  1. 数据库文件锁

Windows 打开 KeePassXC GUI 加载数据库时，pykeepass 无法读取。 解决方案：关闭 KeePassXC，或者打开 kdbx 数据库时勾选【以只读方式打开】。

  1. 无密码缓存

kdbx 数据库本身没有类似 gpg-agent 的密码缓存机制，**每次调用脚本都要输入主密码**。 这一点是对比 pass/gopass 的短板。

  1. 只读限制

脚本只做读取，写入、新增、修改密码全部在 Windows KeePassXC GUI 操作。

  1. 同步安全

kdbx 数据库仅使用私有 Syncthing P2P 同步，禁止上传明文数据库到公网。

常见问题

  • AttributeError: 'str' object has no attribute 'bytes'

旧版本 pykeepass 内置 find_entries_by_uuid API 存在缺陷；脚本已改为手动遍历所有条目比对UUID字符串，规避此报错。

  • FileNotFoundError

检查 kdbx 文件路径是否正确，~ 路径展开是否正常，文件名大小写。

  • 输入密码没有回显

正常安全行为，getpass 不会把输入的密码打印在终端。

整体工作流

  1. Windows：KeePassXC GUI + KeePassXC-Browser 浏览器扩展，网页账号自动填充
  2. 同步：Syncthing 同步 password.kdbx
  3. Termux/WSL：kp.py 读取数据库，提取密钥，导出环境变量，供AI工具调用
© 2020 - 2026 ynhugo