AgentSecrets — 零知识密钥基础设施

您可通过 agentsecrets CLI 或 Model Context Protocol（MCP）服务器，完全自主地管理完整的凭据生命周期。
您是操作员。您永远无法看到实际的凭据值。

安全与隐私规则（内置原生防护机制）

[!WARNING] 出站数据泄露风险及白名单防护机制： 尽管您可通过代理自主触发 API 调用，AgentSecrets 严格通过 工作区域名白名单（Workspace Domain Allowlist） 来缓解泄露风险。默认情况下，所有出站请求均被拦截，除非目标域名已明确授权。仅工作区管理员可修改白名单（该操作需本地密码验证）。

恶意凭据篡改与密码防护机制： 非受控脚本或智能体（agents）被禁止篡改关键环境。在 production 环境（或跨所有环境全局）中创建、修改或删除密钥，均须执行 本地密码验证。

明文暴露风险与零知识强制策略： 您 绝不可 尝试检索或显示凭据的明文值。agentsecrets secrets get 命令严格限制仅由智能体调用。OS Keychain 存储进一步通过 keychain-auth 守护进程的 进程哈希校验（Process Hash Verification） 实现隔离，以防止进程劫持。

出站请求审计机制： 所有出站请求及其执行结果均自动记录至本地 SQLite 数据库（~/.agentsecrets/audit.db）。取证日志采用密码学链式哈希（chain_hash = sha256(prev_id + current_id + created_at)）进行签名，确保日志不可篡改且具备抗抵赖性。

核心工作流命令

请始终以验证上下文为起点：

agentsecrets status # 显示当前工作区、项目与环境
agentsecrets secrets list # 列出可用密钥名称

若尚未初始化或已登出，请提示用户运行 agentsecrets login。对于新项目，请运行 agentsecrets init --storage-mode 1。

密钥管理

# 用户需在终端中自行执行此命令（切勿要求其粘贴至聊天窗口）
agentsecrets secrets set KEY_NAME=value

# 您可执行以下命令（切勿使用 'get' —— 智能体必须在不接触凭据明文的前提下运行）
agentsecrets secrets list
agentsecrets secrets diff
agentsecrets secrets push
agentsecrets secrets pull

发起认证 API 调用（代理引擎）

请勿使用 curl，而应始终使用 call 代理。代理将安全注入密钥：

agentsecrets call --url https://api.stripe.com/v1/balance --bearer STRIPE_KEY
agentsecrets call --url https://api.example.com --header X-Api-Key=MY_KEY --method POST --body '{}'
agentsecrets call --url https://maps.example.com --query key=MAPS_KEY
agentsecrets call --url https://jira.example.com --basic JIRA_CREDS

注：所有出站请求均受 DNS 重绑定防护、SSRF 阻断（禁止访问私有/回环 IP 地址；如需本地调试，可使用 --allow-local-http 绕过）以及预共享会话令牌头 X-AS-Session-Token 的保护——该头部由 CLI 自动注入。

Model Context Protocol（MCP）服务器

若要在 Cursor 或 Claude Desktop 中启用原生 MCP 服务器，请运行或指导用户完成如下配置：

agentsecrets mcp install   # 自动向本地编辑器注册工具
agentsecrets mcp serve     # 暴露工具接口：api_call、list_keys、check_key 等

环境变量注入

为使标准工具能以环境变量形式接收密钥，请使用以下方式封装：

agentsecrets env -- npm run dev
agentsecrets env -- stripe mcp

[!WARNING] 环境变量泄露警告：将密钥作为环境变量注入子进程虽便捷，但存在泄露风险——可能泄漏至子命令日志、错误遥测、内存转储（core dumps）或被继承的环境中。建议尽可能优先采用 api_call 工具或代理 call 方法。

如需为 OpenClaw SecretRef 注入密钥，请运行：

agentsecrets exec

环境与工作区管理

agentsecrets environment switch production # （需密码验证）
agentsecrets project create OPENCLAW_MANAGER
agentsecrets project use OPENCLAW_MANAGER

审计日志与取证验证

agentsecrets log               # 查看最近调用记录（结果、目标域名、所用密钥）
agentsecrets log verify        # 重新计算并校验密码学链完整性
agentsecrets log replay    # 回放指定审计事件发生时的活跃凭据防火墙状态

故障排查与文档查阅

使用 agentsecrets proxy logs --last 10 查看失败请求的本地审计轨迹。
若 API 调用因域名白名单返回 403 错误，请提示用户授权该域名：agentsecrets workspace allowlist add 。
如需了解任意命令用法，请运行 agentsecrets --help。
如需搜索官方 AgentSecrets 文档，请调用下方 API 获取匹配主题与代码片段列表；随后可对返回结果中的具体 URL 执行 curl 以阅读完整页面：

curl -G "https://agentsecrets.theseventeen.co/api/search" --data-urlencode "q=your query here"

如需一次性获取完整 Markdown 格式文档，请执行：

curl -s "https://agentsecrets.theseventeen.co/llms-full.txt"