🔐 凭证保险库

用于 OpenClaw 代理的加密凭证存储。停止以明文形式存储 API 密钥。

概述

凭证保险库提供基于 AES-256-GCM 的本地加密存储，用于保存 API 密钥、令牌及其他敏感信息。避免将凭证分散在 .env 文件中，通过集中管理加密保险库，并支持审计日志和过期时间追踪。

功能特性

• AES-256-GCM 加密，使用 PBKDF2 密钥派生（600,000 次迭代）
• 支持凭证的增删改查（CRUD）操作
• 基于标签的组织方式（按技能、项目等分类）
• 环境变量注入，便于集成
• 过期时间追踪与提醒功能
• 审计日志记录（谁在何时访问了哪些凭证）
• 会话式解锁机制（无需重复输入密码）

安装

cd ~/ubik-collective/systems/ubik-pm/skills/credential-vault
uv sync

快速入门

# 初始化保险库（一次性设置）
uv run vault init

# 解锁保险库
uv run vault unlock

# 添加凭证
uv run vault add OPENAI_API_KEY "sk-..." --tag openai
uv run vault add TAVILY_API_KEY "tvly-..." --tag tavily --expires 2026-12-31

# 列出所有凭证
uv run vault list

# 获取某个凭证
uv run vault get OPENAI_API_KEY

# 导出供技能使用
eval $(uv run vault env --tag tavily)

# 使用完毕后锁定
uv run vault lock

安全模型

加密机制

• 主密码 → PBKDF2-SHA256（600,000 次迭代）→ 256 位密钥
• 每个秘密使用 AES-256-GCM 加密（每个条目使用唯一随机数）
• 身份验证标签确保数据完整性
• 主密码不被存储（仅保存验证哈希）

存储结构

• 保险库文件：~/.openclaw/vault/vault.enc.json（加密状态）
• 审计日志：~/.openclaw/vault/audit.log（明文，不含凭证值）
• 会话密钥：~/.openclaw/vault/session（临时文件，锁定时清除）

权限控制

• 保险库文件权限：0600（仅所有者可读写）
• 会话密钥在执行 vault lock 后删除

威胁模型

可防范的情况：

• ✅ 意外泄露凭证（如提交到 Git、日志输出）
• ✅ 随意浏览文件系统
• ✅ 恶意软件读取 .env 文件

无法防范的情况：

• ❌ 键盘记录器（可捕获主密码）
• ❌ 系统级提权攻击
• ❌ 保险库解锁期间的内存转储

使用示例

详见 [EXAMPLE.md](./EXAMPLE.md) 了解详细使用模式。

命令说明

vault init

使用主密码初始化新的保险库。

vault unlock

解锁当前会话中的保险库。

vault lock

锁定保险库并清除会话密钥。

vault status

显示保险库状态（锁定/解锁状态、凭证数量）。

vault add KEY_NAME [VALUE] [--tag TAG] [--expires DATE]

添加或更新一条凭证。若未提供 VALUE，则安全提示输入。

vault get KEY_NAME

检索并解密指定凭证。

vault list [--tag TAG]

列出所有凭证（值被掩码显示）。可按标签过滤。

vault remove KEY_NAME [-y]

删除一条凭证。除非使用 -y 参数，否则会提示确认。

vault env [--tag TAG]

将凭证导出为 KEY=VALUE 格式，用于环境变量注入。

示例：

eval $(uv run vault env --tag openai)
echo $OPENAI_API_KEY  # 现在可用

vault audit [--last N]

查看最近的审计日志条目。

vault expiring [--days N]

检查未来 N 天内即将过期的凭证（默认为 7 天）。

vault rotate KEY_NAME [NEW_VALUE]

替换某条凭证的新值（保留原有标签和元数据）。

与技能的集成

模式一：运行技能前注入凭证

# Tavily 搜索技能
eval $(uv run vault env --tag tavily)
uv run scripts/search.py "OpenClaw 发布日期"

模式二：技能直接从保险库读取

from lib.store import Store

store = Store()
# 假设用户已提前解锁保险库
api_key = store.get("TAVILY_API_KEY")

模式三：在 HEARTBEAT.md 中自动解锁检查

# HEARTBEAT.md
检查保险库是否锁定。若是，提示用户解锁后再执行每日任务。

最佳实践

1. 统一使用标签 — 按技能名称打标签，便于筛选
2. 设置过期时间 — 跟踪 API 密钥需要轮换的时间
3. 空闲时及时锁定 — 不使用时运行 vault lock
4. 每台机器一个保险库 — 不跨设备同步保险库文件
5. 定期轮换凭证 — 使用 vault expiring 检查即将过期的凭证
6. 定期审查审计日志 — 定期检查 vault audit 输出

局限性

• 仅限本地使用 — 无网络同步功能（设计如此）
• 单用户模式 — 不支持多用户访问控制
• 无自动备份 — 用户需自行备份 ~/.openclaw/vault/ 目录
• 会话密钥暂存磁盘 — vault unlock 会将解密密钥写入磁盘，直到执行 vault lock 才清除

故障排查

“保险库已锁定”

运行 uv run vault unlock 并输入主密码。

“主密码错误”

请仔细核对密码。若遗忘，需重新初始化（将丢失所有凭证）。

“保险库未初始化”

运行 uv run vault init 创建新保险库。

“重启后会话密钥仍存在”

会话文件在 vault lock 时会被清除，但不会在重启时自动清理。请手动执行 vault lock。

开发

运行测试

uv run pytest

添加测试用例

参考 tests/test_roundtrip.py 获取示例。

许可证

MIT-0（等同于公共领域）