OpenClaw 密钥管理技能 🔐

一套全面的安全密钥管理系统，即使内存文件遭到泄露，也能保护您的 AI 助手的凭据安全。

适用场景

• 在将任何 API 密钥、密码或令牌存入 OpenClaw 内存文件之前
• 需要保护已存储在 MEMORY.md 或日常日志中的现有凭据时
• 所有处理敏感认证数据的 OpenClaw 部署
• 与他人共享工作区或备份至云存储时

核心功能

🔒 强加密机制

• 采用 AES-256-GCM 认证加密算法
• 使用 PBKDF2-HMAC-SHA256 进行密钥派生（100,000 次迭代）
• 为每个凭据生成独立的随机 salt 和初始化向量（IV）
• 通过认证标签实现篡改检测

🧠 内存安全机制

• 凭据仅在活跃使用期间于内存中存在 30 秒
• 自动对明文凭据执行安全清零操作
• 锁定内存页以防止交换到磁盘
• 运行时凭据缓存，并支持自动清理

📁 职责分离原则

• 凭据永不存入 MEMORY.md 或日常日志文件
• 专用加密保险库位于 .secrets/vault.json.enc
• 自动检测并拦截任何尝试记录凭据的行为
• 内存文件中仅保留安全引用格式，如 {SECRET:api_key_name}

⚙️ 双重安全模式

• 便捷模式：系统主密钥由机器 ID 与主机名派生（自动解密）
• 高安全模式：每次会话启动时均需输入用户口令
• 可通过 config/key_management.json 文件配置

🛠️ 简易管理能力

• 提供 CLI 工具用于添加、获取和管理凭据
• 内置自动备份系统，支持带版本号的加密备份
• 提供迁移工具，可从内存文件中提取已有凭据
• 深度集成 OpenClaw 现有内存架构

安装

前提条件

• OpenClaw 2026.3.13 或更高版本
• Node.js 18+（用于加密模块）
• 标准类 Unix 系统（Linux/macOS）

设置步骤

# 1. 克隆或复制本技能至您的 skills 目录
cp -r openclaw-key-management-skill ~/.openclaw/your-workspace/skills/

# 2. 初始化密钥保险库
cd ~/.openclaw/your-workspace
./skills/openclaw-key-management/scripts/key_manager.sh init

# 3. 配置安全模式（可选）
# 编辑 skills/openclaw-key-management/config/key_management.json
# 将 "master_key_mode" 设为 "system_key"（默认）或 "passphrase"

# 4. 迁移已有凭据（如有）
./skills/openclaw-key-management/scripts/key_manager.sh migrate

使用方法

添加凭据

# 添加新凭据
./skills/openclaw-key-management/scripts/key_manager.sh add my_api_key

# 添加带元数据的凭据
./skills/openclaw-key-management/scripts/key_manager.sh add instreet_api_key

获取凭据

# 获取凭据值（自动解密）
./skills/openclaw-key-management/scripts/key_manager.sh get my_api_key

# 列出所有已存储的凭据
./skills/openclaw-key-management/scripts/key_manager.sh list

与 OpenClaw 集成

在 OpenClaw 工作流中，请使用如下安全占位符格式引用凭据：

### 外部服务
- **API 密钥**: {SECRET:my_api_key}

系统将在运行时自动捕获此类引用，并提供解密后的值。

安全架构

文件结构

workspace/
├── .secrets/                    # 加密凭据目录
│   ├── master.key               # 加密的主密钥
│   ├── vault.json.enc           # 主加密凭据保险库
│   ├── backup/                  # 带版本号的加密备份
│   └── temp/                    # 临时运行时文件
├── skills/openclaw-key-management/
│   ├── scripts/key_vault.js     # Node.js 加密模块
│   ├── scripts/key_manager.sh   # CLI 管理工具
│   └── config/key_management.json # 配置模板
└── MEMORY.md                    # 仅含安全引用：{SECRET:name}

威胁模型与缓解措施

配置选项

config/key_management.json

{
  "version": "1.0",
  "master_key_mode": "system_key", // "system_key" 或 "passphrase"
  "encryption": {
    "algorithm": "aes-256-gcm",
    "pbkdf2_iterations": 100000,
    "salt_length": 16,
    "iv_length": 12
  },
  "runtime": {
    "credential_timeout_seconds": 30,
    "enable_memory_locking": true,
    "auto_cleanup_on_exit": true
  },
  "backup": {
    "enabled": true,
    "max_backups": 10,
    "backup_interval_hours": 24
  }
}

迁移指南

从现有 OpenClaw 部署迁移

1. 备份当前工作区
2. 按安装步骤安装本技能
3. 运行迁移工具：./scripts/key_manager.sh migrate
4. 验证：确认 MEMORY.md 中现已替换为 {SECRET:name} 引用
5. 测试：确保您的工作流仍能正常运行

手动迁移

若自动迁移失败，请手动执行以下步骤：

1. 从内存文件中提取凭据
2. 使用命令添加：./scripts/key_manager.sh add credential_name
3. 将内存文件中的明文值替换为 {SECRET:credential_name}

最佳实践

✅ 推荐做法

• 所有敏感凭据务必使用本技能进行管理
• 定期备份加密保险库
• 生产环境部署请启用高安全模式
• 定期审查并更新配置

❌ 禁止行为

• 切勿在内存文件中以明文形式存储凭据
• 切勿在未加密状态下共享 .secrets/ 目录
• 除非充分理解风险，否则不得禁用内存安全特性
• 避免使用弱系统配置（如过时的 Node.js 版本等）

API 参考

Node.js 模块

const SecureKeyVault = require('./skills/openclaw-key-management/scripts/key_vault.js');
const vault = new SecureKeyVault('/path/to/workspace');

await vault.initialize();
await vault.setSecret('api_key', 'your-secret-value');
const secret = await vault.getSecret('api_key');

CLI 命令

• init — 初始化密钥保险库
• add NAME — 添加新密钥
• get NAME — 获取密钥值
• list — 列出全部密钥
• backup — 创建备份
• migrate — 迁移已有凭据

故障排查

常见问题

• “未找到保险库文件”：请先运行 init 命令
• 解密失败：请确认系统未发生变更（如机器 ID、主机名）
• 权限错误：请确保 .secrets/ 目录具有正确的文件权限
• 内存问题：若需处理大量凭据，请增加 Node.js 内存限制

恢复流程

• 丢失主密钥（便捷模式）：从备份恢复，或重新迁移凭据
• 遗忘口令（高安全模式）：无法恢复（设计使然）
• 保险库损坏：从 .secrets/backup/ 中最新备份恢复

贡献指南

本技能遵循 OpenClaw AgentSkills 规范，欢迎提交贡献：

• 安全增强改进
• 新增加密算法支持
• 与 OpenClaw 核心更深度集成
• 文档质量提升

许可证

MIT 许可证 — 免费使用、修改与分发。

请注意：安全是一种持续过程，而非一次性产品。本技能提供了强有力的防护能力，但您仍须在整个 OpenClaw 部署中贯彻实施各项安全最佳实践。