---
summary: "秘密工具如何让代理请求它从未见过的凭据"
read_when:
  - "您希望代理在不进入聊天的情况下获取 API 密钥"
  - "您正在回答或调试凭据请求提示"
  - "您需要秘密工具架构、存储或通道行为"
title: "密钥"
---

`secrets` 可以让代理在您看不到凭证的情况下向您询问凭证。代理命名一个条目，您在受信任的提示中键入该值，然后网关将其直接写入共享秘密存储中。该值永远不会出现在聊天、会话记录、工具结果或模型上下文中 - 代理仅接收条目元数据及其存储 SecretRef。

该工具在主要代理会话中可用，而不仅仅是在主要对话中。子代理和 ACP 工作会话不会收到它。

它默认启用并受正常工具策略管理 - 没有专用的配置密钥。要删除它，请像任何其他工具一样拒绝它（例如 `openclaw.json` 中的 `tools.deny: ["secrets"]`）。允许列表和工具配置文件以相同的方式应用。

工具描述告诉代理首先列出元数据，然后仅请求任务所需的缺失凭据以及名称和原因。对于出口使用，它也建议确切的目标主机。

## <a id="actions"></a> 操作

- `request` — 向人员询问凭证并将其存储在 `STRIPE_API_KEY` 等名称下。请求仅受保护：`env` 值可通过 `list` 读取，因此请求该值将违反屏蔽提示所做出的承诺。代理可能会建议 `allowedHosts` 并在提示中显示一个简短的 `reason`，并且该工具会一直阻塞，直到您回答、跳过或超时（默认情况下为 15 分钟，`timeoutSeconds` 限制为 30-3600 秒）。这是最长的人工等待时间，可能会提前取消或整体运行超时。该请求不会延长明确的运行预算。该请求绑定到请求代理运行。如果该权限在您回答之前关闭，则挂起的提示将被取消，并且写入将被拒绝。
- `list` — 条目元数据：名称、种类、允许的主机和上次更新。从结构上看，列表中不存在秘密值。操作员设置的 `env` 条目显示了它们的值，因为这些条目无论如何都会被注入到执行环境中，并且在设计上是代理可读的。
- `delete` — 按名称软删除条目。删除的条目将在 30 天后被清除。

故意不执行写入代理提供的值的操作。如果某个值必须进入商店，则该值通过人工提示、`/settings/secrets` 页面或 [`openclaw secrets store` CLI](/cli/secrets) 到达。

## <a id="answering-a-request"></a> 回答请求

Web Control UI 将提示停靠在带有屏蔽输入的作曲器上方。使用眼睛按钮显示或隐藏您在提交之前输入的内容。每个问题的值开始隐藏，并且显示它不会将其发送给代理。提示始终显示谁在询问（代理和会话）、条目名称、代理声明的原因以及允许的主机的可编辑列表，因此您对凭证的使用位置拥有最终决定权。如果该名称已存在，则会出现提示，并显示该条目上次更新的时间和人员。提交会替换存储的值。网关准确保留提交的值，包括前导或尾随空格。 Web、TUI 和 Apple 请求字段是单行。使用 CLI 的 `--value-file` 输入作为多行凭证。

连接网关的 TUI 还接受通过屏蔽输入的请求：键入的字符显示为项目符号，并且永远不会添加到聊天日志或输入历史记录中。提示显示条目名称、原因和建议的允许主机。 TUI 中的主机列表是只读的。提交接受显示的列表。如果您需要在提交前进行编辑，请使用 Control UI。 **Skip** 拒绝该请求。 Esc 使其保持挂起状态，然后 `/question` 重新打开它。切勿在普通作曲家中输入凭据。

本地模式（`openclaw chat` 或 `openclaw tui --local`）无法满足存储绑定请求。代理收到阻止程序，指示操作员运行 `openclaw secrets store` 或将 Control UI 与正在运行的网关一起使用。本地问题提示支持屏蔽输入，但仅此并不能提供网关的秘密存储写入和运行时刷新流程。

如果代理忽略主机建议，则替换请求将从条目的当前主机开始。新条目以空列表开始。明确为空的提案将保持为空。提交会保存显示的列表或您的编辑，即使在提示未决时另一个写入更改了条目。清除列表会禁用出口替换，同时通过配置 SecretRefs 保持凭证可用。

一旦存储写入提交，请求就会得到答复，并且无法再次提交。稍后的运行时刷新失败不会撤消该写入：解决报告的提供程序错误并运行 `openclaw secrets reload`，而不是重新提交。

同一工具结果从一次后续元数据读取中报告 `status: "stored"`、SecretRef 和 `currentPolicy`。这是条目的当前主机列表，您可以编辑它，而不是网关配置或不可变的批准收据：另一个写入可能已更改它。 `available` 包括完整的允许主机列表。空列表意味着没有出口。如果序列化列表超过 512 个字符，`omitted` 仅报告 `allowedHostCount`。 `missing`、`kind_changed` 和 `unavailable` 表示条目消失、变成 `env` 条目或没有完整的经过验证的主机策略。不会撤消保存的结果或邀请重新提交。代理必须报告当前主机而不是其建议，并且在完整列表不可用时不提出主机声明。差异不能解释谁更改了主机或原因，也不是规定网关配置更改的理由。

<Warning>
允许的主机管理网关出口替换，而不是配置 SecretRefs。仅保留应接收凭证的确切主机。空列表可防止出口替换，但仍允许支持的配置字段来解析存储的凭据。出口还需要启用代理。切勿通过在命令、参数、URL、日志或聊天中添加明文来解决缺少代理或目标权限的问题。
</Warning>

跳过提示或让它过期，会告诉代理没有凭证到达 （`no_answer`）。它应该指出阻止者或以最佳判断继续，绝不要求您将凭据粘贴到聊天中。

iOS、macOS 和 Android 使用屏蔽秘密字段渲染同一张卡。 Control UI、TUI 和本机应用程序卡通过现有网关连接到达，不需要 `gateway.publicOrigin` 或公共链接。

聊天渠道从不接受该值。在 Telegram、Discord 和类似表面上，请求作为 Control UI 提示的链接进行传递 — 在聊天消息中键入凭据正是此流程要避免的情况，因此不会将纯文本回复捕获为答案。链接需要启用的 Control UI 和配置的 `gateway.publicOrigin`。如果没有可用的链接，传递会报告可见的阻止程序并取消待处理的请求。打开受信任的 Control UI 或本机应用程序并重试，或要求运营商配置公共源。

创建凭证请求需要 `operator.admin` 以及代理的可信实时运行时权限。仅运行 ID 或管理员连接是不够的。回答只需要正常的问题范围和对该会话的访问权限，因为回答提供了一种价值，而不是阅读价值。

## <a id="using-a-stored-credential"></a> 使用存储的凭据

在网关支持的会话中，不相关提供者的凭据丢失不会阻止打开健康的提供者。代理可以使用该健康模型来请求丢失的条目。在解决其 SecretRef 之前，选择不可用的提供程序仍然会失败。 OpenClaw 不会默默地替换环境或身份验证配置文件凭据。

存储条目是常规共享存储条目（请参阅[秘密管理](/gateway/secrets)）：

- 在接受 SecretRef 的地方使用返回的完整 `ref`（提供者 API 密钥、通道令牌）。默认商店别名为 `{ "source": "store", "provider": "default", "id": "STRIPE_API_KEY" }`。 `secrets.defaults.store` 选择不同的提供商别名。写入受影响的配置和身份验证配置文件引用的触发刷新。成功的刷新还会替换准备好的模型状态，因此稍后的目录读取会对代理模型范围内已有的提供程序使用新凭证。
- `env` 条目是可读值。操作员设置它们，而不是凭证请求流程。
- 仅当启用出口代理 （`secrets.egressProxy.enabled`） 时，`secret` 条目才会通过自动注入的不透明环境哨兵到达网关主机子进程流量。该变量使用存储的条目名称。从命令进程的继承环境中读取它。不要提供秘密模板、覆盖该变量或打印它。替换要求目标与条目允许的主机相匹配。禁用代理后，不会注入受保护的条目。请改用受支持的配置 SecretRef。本机harness shell、沙箱和节点执行不会接收这些受保护的值。提供商故障排除开关 `OPENCLAW_SECRET_SENTINELS=off` 不会禁用受保护存储密封。

受保护的条目不向子进程提供 SSH 或 sudo 密码，包括 `sshpass` 环境变量或 `sudo -S` 标准输入。出口代理替换出站 HTTPS 请求中的凭据；允许的 SSH 主机不启用 SSH 密码验证。 `${secret:NAME}` 不是 exec shell 替换语法。在请求凭证之前检查受支持的使用者是否存在。

对于明确希望网关命令接收明文的操作员，[`openclaw secrets store set`](/cli/secrets) 支持带屏蔽输入的 `--kind env` 或 `--value-file`。此类条目可由代理通过 `secrets list` 和 Gateway exec 读取；他们不遵守受保护的秘密不披露承诺。使用继承的变量而不是将其值复制到命令中。沙箱、节点和本机harness shell 执行不接收存储环境条目。

网关主机执行程序在运行中第一次执行时捕获一个存储快照。可以包括在该点之前存储的凭证。此后，添加、替换、删除和主机编辑不会刷新该运行的快照。开始新的运行来观察它们。成功的凭据请求并不保证已经运行的 exec 工具可以使用新值。

每个托管命令都会从该快照接收自己的代理授权。后台命令在原始回合结束后保留​​访问权限。进程退出、取消、超时或网关关闭撤销授权并关闭其连接；其他命令保留自己的授权。已经交给上游传输的字节不能被撤回。

## <a id="related"></a> 相关内容

- [询问用户](/tools/ask-user) — 用于非凭证决策的结构化问题。凭证永远不是对一个人的有效答案