Vault Enhancements w/ UI v3.0.0

OpenClaw 控制面板的 Vault 后端 API 密钥管理功能。密钥存储在安全文件中（~/.openclaw/secrets.json，权限 0600），并通过 OpenClaw 内置的 Secrets System 进行引用。AI 代理不会看到您的密钥。

状态：✅ 活跃

功能

1. Vault 后端存储

密钥存储于 ~/.openclaw/secrets.json（文件权限 0600）。保存密钥时，UI 将：

1. 将值写入 Vault 文件
2. 在 openclaw.json 中配置文件密钥提供者（如尚未存在）
3. 将明文配置值替换为 SecretRef 对象
4. 显示重启通知 —— 用户必须重启网关以使更改生效

迁移前配置：

{
  "env": {
    "OPENAI_API_KEY": "sk-proj-abc123..."
  }
}

迁移后配置：

{
  "env": {
    "OPENAI_API_KEY": { "source": "file", "provider": "default", "id": "/OPENAI_API_KEY" }
  },
  "secrets": {
    "providers": {
      "default": { "source": "file", "path": "~/.openclaw/secrets.json", "mode": "json" }
    },
    "defaults": { "file": "default" }
  }
}

**Vault 文件（~/.openclaw/secrets.json）：**

{
  "OPENAI_API_KEY": "sk-proj-abc123..."
}

2. 一键迁移

当检测到明文密钥时，“🔒 迁移到 Vault”按钮将出现。它会：

• 扫描 openclaw.json 中所有明文 API 密钥
• 将每个密钥移至 Vault 文件
• 在配置中用 SecretRef 对象替换
• 如需自动配置文件提供者
• 报告已迁移的内容

3. 动态密钥发现

UI 会自动扫描整个配置中的 API 密钥 —— 无需硬编码列表。

检测模式： apiKey, api_key, token, secret, *_KEY, *_TOKEN, *_SECRET

扫描位置：

• env.* —— 环境变量
• skills.entries.*.apiKey —— 技能专属密钥
• messages.tts.*.apiKey —— TTS 提供商密钥
• 任意嵌套配置路径

已知提供者 会显示友好名称、描述和“获取密钥 ↗”链接：

4. Vault 状态横幅

页面顶部显示：

• 🔒 Vault 已启用（绿色）—— 所有密钥均在 Vault 中，提供者已配置
• ⚠️ 检测到 X 个明文密钥（黄色）—— 推荐进行迁移

5. 密钥状态徽章

每个密钥行显示：

• VAULT（绿色）—— 存储在安全的 Vault 文件中
• PLAINTEXT（黄色）—— 仍以明文字符串形式存在于配置中
• NOT SET（灰色）—— 未配置

6. 仅 Vault 密钥区域

存储在 Vault 中但未被任何配置路径引用的密钥将显示在专用的“仅 Vault 密钥”卡片中。这些是手动创建或由技能生成但无对应环境/配置条目的密钥。每项显示：

• 🔒 图标 + 密钥名称（等宽字体）
• 密钥值预览（部分隐藏）
• 删除按钮

7. 手动 "+ 添加密钥" 表单

Vault 标签页标题包含一个 "+ 添加密钥" 按钮，点击后展开内联表单：

• KEY_NAME 输入框（等宽字体，推荐使用 UPPER_SNAKE_CASE）
• 密钥值 输入框（密码类型）
• 保存 / 取消 按钮
• 写入 Vault 时设置 envEntry: false —— 不创建配置条目，不触发重启
• 密钥立即出现在“仅 Vault 密钥”区域

8. 重启通知横幅

当 Vault 写入触发配置变更时，会出现黄色警告横幅：

⚠ 新增密钥需要重启网关才能生效。

[立即重启]

该横幅将持续显示，直到用户点击“立即重启”或刷新页面。此功能取代了此前导致意外重启的自动重载行为。

9. 技能 Vault 密钥选择器

在技能标签页中，声明了 primaryEnv 的技能将使用 Vault 密钥选择器，而非原始密码输入框：

未绑定时：

• 下拉菜单显示所有 Vault 密钥（带 🔒 图标）
• 占位符：“为 ENV_NAME 选择 Vault 密钥…”
• 选择密钥后，在 skills.entries.<key>.apiKey 中写入 SecretRef
• “＋ 添加新 Vault 密钥…” 选项打开内联创建表单

已绑定时：

• 显示 🔒 KEY_NAME 及“解除绑定”按钮
• 解除绑定将从配置中移除 SecretRef

内联密钥创建：

• 输入 KEY_NAME 和密钥值字段
• “保存并绑定” 创建 Vault 密钥，并一步完成与技能的关联
• 密钥也出现在 Vault 标签页的“仅 Vault 密钥”区域

10. 技能默认展开

所有技能组（工作区、内置、托管）默认展开（<details open>），提升可发现性。此前工作区和内置技能组默认折叠。

11. 认证配置文件显示

存储在 Vault 中的认证配置文件密钥（来自 auth-profiles.json）将按状态列出。后端 RPC 支持列出、错误重置和删除操作。

架构

安全模型

markdown

┌──────────────────────────────────────────────────────────┐

│ 浏览器 │

│ ┌──────────────────────────────────────────────────┐ │

│ │ Vault 选项卡 │ │

│ │ ┌──────────────────────────────────────────┐ │ │

│ │ │ OpenAI: [••••••••••] [保存] [✕] 🟢已启用 │ │ │

│ │ │ Anthropic: [ ] [保存] ⚪未设置 │ │ │

│ │ │ + 添加密钥 [KEY_NAME] [值] [保存] │ │ │

│ │ └──────────────────────────────────────────┘ │ │

│ │ │ │

│ │ Skills 选项卡 │ │

│ │ ┌──────────────────────────────────────────┐ │ │

│ │ │ whisper-api: 🔒 OPENAI_API_KEY [解除链接] │ │ │

│ │ │ sag: [选择 Vault 密钥 ▾] │ │ │

│ │ └──────────────────────────────────────────┘ │ │

│ └──────────────────────────────────────────────────┘ │

│ │ │

│ ▼ (直接 RPC 调用，不通过代理) │

└───────────────────────────┼───────────────────────────────┘

│

┌───────▼───────┐

│ 网关 │

│ secrets.write │

│ skills.update │

└──┬─────────┬──┘

│ │

┌────────▼──┐ ┌──▼────────────┐

│ secrets. │ │ openclaw.json │

│ json │ │ (仅包含 SecretRef │

│ (0600) │ │ 对象) │

└────────────┘ └────────────────┘

后端 RPC 接口

Skills 状态集成

SkillStatusEntry 包含 vaultKeyId 字段，该字段读取的是原始配置 JSON（非运行时解析后的配置，其中 SecretRef 已被替换为实际值）。此功能通过 extractVaultKeyIdFromConfig() 实现，直接读取并缓存 openclaw.json，检查 skills.entries.<key>.apiKey 中是否存在 SecretRef 对象。

重启行为

不自动重启。 之前 secrets.write 会调用 reloadSecrets()，可能触发网关重启。现在：

• 仅更新 Vault 的操作（envEntry: false）不会修改配置 —— 无需重启
• 修改配置的操作返回 restartNeeded: true —— UI 显示重启提示横幅
• Skills 与 Vault 关联时通过 writeConfigFile() 写入配置 —— 触发配置文件监视器，导致网关重启（由配置监视系统固有机制决定）

OpenClaw 密钥系统集成

本技能使用 OpenClaw 内置的密钥系统（src/secrets/）：

• 文件提供者： { source: "file", path: "~/.openclaw/secrets.json", mode: "json" }
• SecretRef 格式： { source: "file", provider: "default", id: "/<KEY_NAME>" }
• 运行时解析： prepareSecretsRuntimeSnapshot() 在网关启动时解析所有引用
• 安全性： 检查文件权限（0600）、所有权，并设置路径保护

该密钥系统还支持 env 和 exec 提供者，适用于高级场景（如环境变量、外部密钥工具命令）。文件提供者是此 UI 的默认选项。

修改的文件（OpenClaw 仓库中的源码位置）

参考文件

markdown

apikeys-ui/

├── SKILL.md # 此文件

├── INSTALL_INSTRUCTIONS.md # 逐步安装说明（旧版）

└── reference/

├── apikeys-controller.ts # UI 控制器（Vault 标签页）

├── apikeys-views.ts # UI 视图（Vault 标签页）

├── secrets-rpc.ts # 后端 Vault RPC 接口

├── skills-controller.ts # UI 控制器（技能 Vault 集成）

├── skills-views.ts # UI 视图（Vault 密钥选择器）

├── skills-status.ts # 后端技能状态，包含 vaultKeyId

└── skills-rpc.ts # 后端技能更新 RPC 接口

核心设计决策

1. 保存后不自动重启 — secrets.write 不再调用 reloadSecrets()。通过带有“立即重启”按钮的提醒横幅，让用户自行决定何时重启。

1. 仅限 Vault 的密钥 — 使用 envEntry: false 创建的密钥不会出现在配置中。通过单独的 secrets.list 调用获取所有 Vault 条目，并在专用区域显示未被引用的孤立密钥。

1. 直接读取原始配置以识别 vaultKeyId — 运行时会将 SecretRef 解析为字符串，因此 loadConfig() 返回的是已解析的值。extractVaultKeyIdFromConfig() 直接读取原始 JSON 文件（带 mtime 缓存）以检测 SecretRef 对象。

1. 技能面板默认展开 — 所有 <details> 组合均默认展开，提升用户体验。此前折叠默认的隐藏技能需要额外配置。

1. 技能使用 Vault 引用，而非明文 — 具有 primaryEnv 的技能不再使用密码输入框，而是提供一个 Vault 密钥选择下拉菜单。链接操作会将 SecretRef 写入配置中的 skills.entries.<key>.apiKey。

1. 从技能中内联创建密钥 — 技能下拉菜单中的“＋ 添加新 Vault 密钥…”功能可在一步操作中创建 Vault 条目并完成关联，降低使用门槛。

更新日志

v3.0.0

• 手动“+ 添加密钥”表单 — 在 Vault 标签页头部新增，可在无配置条目的情况下创建 Vault 密钥
• 仅 Vault 密钥区域 — 显示未被配置引用的 Vault 中的密钥
• 重启通知横幅 — 黄色警告提示，含“立即重启”按钮，替代自动重载
• 技能 Vault 密钥选择器 — 为具有 primaryEnv 的技能替换原始密码输入框，改用下拉菜单
• 技能内联密钥创建 — “＋ 添加新 Vault 密钥…”支持一键创建并关联
• 技能默认展开 — 所有分组默认打开，不再折叠隐藏
• SkillStatusEntry 上的 vaultKeyId — 通过读取原始配置 JSON 检测 SecretRef 对象
• secrets.write 中的 envEntry 参数 — 控制是否创建环境变量块条目
• skills.update 中的 vaultKeyId 参数 — 写入 SecretRef 或解除技能与 Vault 密钥的关联

v2.0.0

• 基于 Vault 的存储 — 密钥存储于 ~/.openclaw/secrets.json（权限 0600），不再以明文形式存在于配置中
• SecretRef 集成 — 配置值被 OpenClaw SecretRef 对象替代，指向 Vault
• 一键迁移功能 — “迁移到 Vault”可批量迁移所有明文密钥
• Vault 状态横幅 — 绿色（全部安全）或黄色警告（检测到明文）
• 密钥标签 — 每个密钥显示 VAULT / PLAINTEXT / NOT SET 状态
• 新增 RPC 接口 — secrets.status、secrets.list、secrets.write、secrets.delete、secrets.migrate
• 插件 UI 注册方式变更 — 从旧导航结构迁移至插件架构（设置组，位置 1）
• 自动提供者配置 — 保存密钥时，若未配置文件密钥提供者，则自动添加

v1.1.0

• 动态密钥发现 — 扫描整个配置文件，不再依赖硬编码列表
• 自动按类别分组（环境 / 技能 / 其他）
• 即使未配置，也显示常用环境密钥

v1.0.0

• 初始版本，包含硬编码的提供者槽位
• 通过 config.patch 实现保存/清除功能