密钥

secrets 让代理可以向你请求凭据，而无需真正看到该凭据。代理命名一个条目，你在受信任的提示中输入值，Gateway 将其直接写入共享机密存储。该值绝不会出现在聊天、会话记录、工具结果或模型的上下文中——代理仅接收条目的元数据及其存储 SecretRef。

该工具在主代理会话中可用，而不仅仅是标准的主对话。子代理和 ACP worker 会话不会获得该工具。

它默认启用，并受常规工具策略约束——没有专门的配置键。若要移除它，请像对待其他工具一样拒绝它（例如在 openclaw.json 中设置 tools.deny: ["secrets"]）。允许列表和工具配置文件同样适用于它。

工具描述要求代理先列出元数据，然后仅请求任务所需的缺失凭据，并提供名称和原因。对于出站使用，它还会提议确切的目标主机。

操作¶

• request — 向人类请求凭据，并以诸如 STRIPE_API_KEY 之类的名称存储。请求仅限受保护机密：env 值可通过 list 读取，因此请求 env 值会打破掩码提示所做的承诺。代理可提议 allowedHosts 和显示在提示上的简短 reason；该工具会一直阻塞，直到你回答、跳过或超时（默认 15 分钟，timeoutSeconds 限制在 30–3600 秒）。这是最大的人类等待时间，可能因提前取消或整体运行超时而终止。请求不会延长显式的运行预算。请求绑定到发起请求的代理运行。如果你回答之前该运行已经结束，待处理的提示会被取消，写入会被拒绝。
• list — 条目元数据：名称、类型、允许的主机以及最后更新时间。机密值在结构上不出现在列表中。操作者设置的 env 条目会显示其值，因为无论如何这些值都会被注入到执行环境中，并且按设计可供代理读取。
• delete — 按名称软删除条目。已删除的条目会在 30 天后清除。

故意没有操作用于写入代理提供的值。如果必须有值进入存储，它只能通过人类提示、/settings/secrets 页面或 openclaw secrets store CLI 到达。

回答请求¶

Web Control UI 会在撰写框上方停靠一个带掩码输入的提示。提示始终显示提问者（代理和会话）、条目名称、代理说明的原因，以及可编辑的允许主机列表，因此你可以最终决定该凭据可用于何处。如果名称已存在，提示会说明这一点，并显示该条目最后更新的时间和更新者。提交后会替换已存储的值。Gateway 会精确保留提交的值，包括前导或尾随空格。Web、TUI 和 Apple 请求字段均为单行。对于多行凭据，请使用 CLI 的 --value-file 输入。

已连接 Gateway 的 TUI 也通过掩码输入接受请求：键入的字符显示为圆点，并且永远不会被添加到聊天日志或输入历史中。提示显示条目名称、原因和建议的允许主机。主机列表在 TUI 中是只读的。提交即接受所显示的列表。如果你需要在提交前编辑列表，请使用 Control UI。跳过表示拒绝请求。Esc 使其保持待处理状态，/question 可重新打开它。切勿在普通撰写框中输入凭据。

本地模式（openclaw chat 或 openclaw tui --local）无法完成绑定存储的请求。代理会收到一个阻塞提示，指示操作者运行 openclaw secrets store，或在运行中的 Gateway 场景下使用 Control UI。本地提问提示支持掩码输入，但仅凭这一点并不能提供 Gateway 的机密存储写入和运行时刷新流程。

如果代理未提议主机，则替换请求会以该条目的当前主机列表开始。新条目以空列表开始。显式空的提议会保持为空。提交时保存所显示的列表或你的编辑内容，即使提示待处理期间另一次写入更改了该条目。清空列表会禁用出站替换，同时仍允许通过配置 SecretRef 使用该凭据。

一旦存储写入提交，请求即被视为已应答，无法再次提交。稍后的运行时刷新失败不会撤销该写入：请解决所报告的提供方错误并运行 openclaw secrets reload，而不是重新提交。

该工具结果会在一次后续元数据读取中报告 status: "stored"、SecretRef 和 currentPolicy。这是该条目的当前主机列表，你可以编辑；它不是 Gateway 配置，也不是不可变的批准回执：另一次写入可能已更改它。available 包含完整的允许主机列表。空列表表示没有出站。如果序列化列表超过 512 个字符，omitted 仅报告 allowedHostCount。missing、kind_changed 和 unavailable 表示条目已消失、变成了 env 条目，或没有完整且经过验证的主机策略。这些都不会撤销已保存的结果，也不会引发重新提交。代理必须报告当前主机，而不是它的提议；当完整列表不可用时，不得对主机做出任何断言。差异并不能解释谁更改了主机或原因，也不是规定 Gateway 配置变更的理由。

跳过提示或让其过期，会告诉代理没有凭据到达（no_answer）。代理应说明阻塞原因，或凭最佳判断继续，绝不应要求你将凭据粘贴到聊天中。

iOS、macOS 和 Android 渲染同一张卡片，其中机密字段带掩码。 Control UI、TUI 和原生应用卡片通过现有 Gateway 连接送达， 不需要 gateway.publicOrigin 或公共链接。

聊天渠道从不接受该值。在 Telegram、Discord 及类似界面上， 请求以指向 Control UI 提示的链接形式送达——在聊天消息中输入凭据 正是此流程旨在避免的情况，因此纯文本回复不会被捕获为答案。链接需要已启用的 Control UI 和已配置的 gateway.publicOrigin。如果没有可用链接，投递 会报告可见的阻塞项并取消待处理请求。打开受信任的 Control UI 或原生应用 并重试，或要求操作员配置公共源。

创建凭据请求需要 operator.admin 以及代理的受信任、实时运行时权限。 仅有运行 ID 或管理员连接是不够的。回答只需要常规问题作用域和对该会话的 访问权限，因为回答是提供值而不是读取值。

使用已存储的凭据¶

在由 Gateway 支持的会话中，无关提供商缺失凭据不会阻塞健康提供商上的 回合。代理可以使用该健康模型请求缺失的条目。选择不可用的提供商仍会失败， 直到其 SecretRef 解析。OpenClaw 不会静默替换环境或 auth-profile 凭据。

已存储条目是常规共享存储条目（参见 密钥管理）：

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

Gateway 宿主 exec 在运行中的首次执行时捕获一个存储快照。 在该点之前存储的凭据可以被包含。之后，添加、 替换、删除和宿主编辑不会刷新该运行的快照。启动 新运行以观察它们。成功的凭据请求并不保证已在运行的 exec 工具可以使用新值。

每个受管理命令都会从该快照获得自己的代理授权。后台 命令在源回合结束后仍保留访问权限。进程退出、取消、 超时或 Gateway 关闭会撤销授权并关闭其连接；其他 命令保留自己的授权。已交给上游传输的字节无法召回。

相关¶

• 询问用户 — 用于非凭据决策的结构化问题。凭据永远不是其中一个有效答案