Vincent - 用于代理的凭据管理

使用此技能安全地管理应用程序所需的凭据——API 密钥、密码、OAuth 令牌、SSH 密钥，或结构化的用户名/密码对。代理创建一个密钥，用户（或代理）设置其值，然后代理通过 CLI 将值直接写入 .env 文件。凭据值不会出现在代理的上下文或标准输出中。

当代理在构建需要凭据的应用程序时（例如第三方 API 密钥），此功能非常有用。无需将凭据粘贴到聊天中（这会导致凭据进入代理上下文），用户可通过 Vincent 控制台设置凭据，代理则通过 CLI 将其写入 .env 文件。

所有命令均使用 @vincentai/cli 包。API 密钥会自动存储并解析——您无需处理原始密钥或文件路径。

安全模型

该技能旨在将凭据从代理的上下文窗口中隔离。

工作原理： secret env CLI 命令从 Vincent 服务器获取凭据，并直接将其写入磁盘上的 .env 文件。值不会输出到标准输出，也不会出现在代理的对话上下文中。许多代理框架会屏蔽读取 .env 文件的操作，因此即使文件存在于磁盘上，代理也无法读回它。代理所构建的应用程序在运行时正常读取 .env 文件。

无需环境变量，因为此技能采用代理优先的初始化方式：代理在运行时调用 Vincent API 创建自己的凭据密钥，API 返回一个作用域受限的 API 密钥。CLI 在创建过程中自动存储返回的 API 密钥。密钥持久化路径（${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/credentials/credentials/ 或 ./credentials/）在本技能的元数据中声明。

覆盖保护机制： 一旦由代理的 API 密钥设置了值，只有相同的 API 密钥才能覆盖它。这防止了其他代理或密钥篡改凭据。该保护在数据库层面以原子方式强制执行。

**所有 API 调用仅发送至 heyvincent.ai**，通过 HTTPS/TLS 加密传输。不与其他端点、服务或外部主机通信。

密钥生命周期：

• 创建：代理运行 secret create 并指定 --type CREDENTIALS —— CLI 自动存储 API 密钥，并返回 keyId 和 claimUrl。
• 设置值：用户通过控制台在认领后设置凭据值，或代理通过 CLI 设置。
• 写入 .env 文件：代理运行 secret env 将值写入 .env 文件，且不暴露值。
• 认领：人工操作员使用认领 URL 申请所有权，并通过 https://heyvincent.ai 管理该密钥。
• 撤销：密钥所有者可随时在 https://heyvincent.ai 上撤销代理的 API 密钥。

密钥类型

以上四种类型均支持相同的创建、设置和 env 工作流。

CREDENTIALS 值格式

CREDENTIALS 值必须是一个包含至少以下一项的 JSON 对象：

• password（字符串）—— 例如：{"username": "alice", "password": "hunter2"}
• secret（字符串）—— 例如：{"accountId": "acct-1", "secret": "top-secret"}

其他字段将原样保留。所有值长度限制为 16KB。

快速入门

1. 检查是否存在现有密钥

在创建新密钥前，请先检查是否已存在：

npx @vincentai/cli@latest secret list --type CREDENTIALS

如果返回了密钥，请使用其 id 作为后续命令的 --key-id。如果没有密钥，则创建一个新的密钥。

2. 创建凭据密钥

npx @vincentai/cli@latest secret create --type CREDENTIALS --memo "Acme API 凭据"

返回 keyId（用于所有后续命令）、claimUrl（与用户共享）和 secretId。

创建后，请告知用户：

“这是您的凭据认领链接：<claimUrl>。请访问 https://heyvincent.ai 使用此链接认领所有权并设置凭据值。”

3. 设置凭据值

选项 A：用户通过控制台设置（推荐）

用户使用认领链接认领密钥，然后在控制台中设置凭据值。这确保值完全不在代理的处理范围内。

选项 B：代理通过 CLI 设置

适用于代理已获取凭据的场景（例如从服务获取 API 密钥）：

npx @vincentai/cli@latest secret set-value --key-id <KEY_ID> --value '{"username": "alice", "password": "hunter2"}'

对于简单字符串类型（API_KEY、SSH_KEY、OAUTH_TOKEN）：

npx @vincentai/cli@latest secret set-value --key-id <KEY_ID> --value "sk-my-third-party-api-key"

4. 写入 .env 文件

一旦值被设置（由用户或代理），即可使用 CLI 将其写入 .env 文件。值不会输出到标准输出。

# 将 API_KEY 密钥写为环境变量
npx @vincentai/cli@latest secret env --key-id <KEY_ID> --env-var ACME_API_KEY

# 对于 CREDENTIALS：提取特定字段
npx @vincentai/cli@latest secret env --key-id <KEY_ID> --env-var DB_PASSWORD --field password

# 写入指定路径（默认：./.env）
npx @vincentai/cli@latest secret env --key-id <KEY_ID> --env-var SERVICE_TOKEN --path ./config/.env

该命令输出确认信息（不含值），以便代理确认操作成功：

{
  "written": "ACME_API_KEY",
  "path": "/path/to/.env",
  "type": "API_KEY"
}

参数说明：

技能：Vincent - 凭据

版本：1.0.69

分块：2/2

行为：

• 若 .env 文件不存在，则创建该文件（权限为 0600）
• 若变量已存在，则就地更新
• 若变量不存在，则追加新行
• 包含特殊字符的值会自动加上引号

5. 在应用中使用

您的应用程序按常规方式读取 .env 文件：

# Node.js 使用 dotenv
require('dotenv').config()
const apiKey = process.env.ACME_API_KEY

# Python 使用 python-dotenv
from dotenv import load_dotenv
load_dotenv()
api_key = os.getenv('ACME_API_KEY')

示例：完整工作流程

# 1. 代理创建一个 CREDENTIALS 类型的密钥
npx @vincentai/cli@latest secret create --type CREDENTIALS --memo "Acme 服务凭据"
# → keyId: abc-123, claimUrl: https://heyvincent.ai/claim/...

# 2. 告知用户通过控制台完成凭据领取并设置值

# 3. 设置完成后，将各个字段写入 .env
npx @vincentai/cli@latest secret env --key-id abc-123 --env-var ACME_USERNAME --field username
npx @vincentai/cli@latest secret env --key-id abc-123 --env-var ACME_PASSWORD --field password

# 结果写入 .env：
# ACME_USERNAME=alice
# ACME_PASSWORD=hunter2

输出格式

secret env 命令输出确认信息的 JSON（不包含凭据值）：

{
  "written": "ACME_API_KEY",
  "path": "/path/to/.env",
  "type": "API_KEY"
}

secret create 命令返回：

{
  "keyId": "abc-123",
  "claimUrl": "https://heyvincent.ai/claim/...",
  "secretId": "sec-456"
}

错误处理

重新关联（恢复 API 访问）

若代理丢失其 API 密钥，凭据所有者可在前端生成一个 重新关联令牌。代理随后用此令牌换取新的 API 密钥。

npx @vincentai/cli@latest secret relink --token <TOKEN_FROM_USER>

CLI 将令牌兑换为新的 API 密钥，自动保存，并返回新的 keyId。重新关联令牌为一次性使用，10 分钟后过期。

重要注意事项

• 凭据值永远不会进入代理的上下文。 secret env 命令直接写入文件——不会将值输出到标准输出。
• 多数代理框架（如 OpenClaw、Claude Code 等）会屏蔽读取 .env 文件，提供额外保护层。
• 创建密钥后，务必与用户共享领取链接。
• 序列化后的值大小限制为 16KB。
• 若因 403 错误拒绝覆盖，表示其他 API 密钥已设置该值。凭据所有者可从控制台进行管理。