密钥
secrets 让智能体(agent)向您请求一个凭证(credential),而它自己永远不会看到该凭证。智能体命名一个条目(entry),您在受信任的提示中输入值,Gateway 会将其直接写入共享的密钥存储库。该值绝不会出现在聊天、会话记录、工具结果或模型的上下文中——智能体只会收到条目元数据及对应的存储 SecretRef。
该工具在主智能体会话中可用,而不仅仅是规范的主对话。子智能体(Subagent)和 ACP 工作会话不会收到该工具。
它默认启用,并受常规工具策略约束——没有专门的配置键。若要移除它,请像拒绝任何其他工具一样拒绝它(例如在 openclaw.json 中设置 tools.deny: ["secrets"])。允许列表(allowlist)和工具配置文件(tool profile)对它的适用方式相同。
工具描述指示智能体先列出元数据,然后仅请求任务所需的缺失凭证,并附上名称和原因。对于出站(egress)使用,它还会提议确切的目标主机。
操作¶
request— 向人类请求一个凭证,并将其存储在诸如STRIPE_API_KEY这样的名称之下。请求仅可针对受保护密钥发出:env值可通过list读取,因此请求env条目会破坏掩码提示所做的承诺。智能体可以在提示上提议allowedHosts和一段简短的reason;工具会一直阻塞,直到您回答、跳过或超时(默认 15 分钟,timeoutSeconds被限制在 30–3600 秒之间)。这是人类等待时间的上限,并可能因提前取消或整体运行超时而中止。该请求不会延长显式的运行预算。该请求绑定到发起请求的智能体运行。如果该授权方在您回答之前关闭,则待处理的提示会被取消,且写入会被拒绝。list— 条目元数据:名称、类型(kind)、允许主机和最后更新时间。密钥值在结构上不会出现在列表中。操作员设置的env条目会显示其值,因为这些值反正会被注入到执行环境中,并且按设计就是智能体可读的。delete— 按名称软删除一个条目。已删除条目将在 30 天后被清除。
刻意没有提供任何写入智能体所提供值的动作。如果一个值必须进入存储库,它只能通过人工提示、/settings/secrets 页面或 openclaw secrets store CLI 进入。
回答请求¶
网页版 Control UI 会在输入区(composer)上方停靠一个带掩码输入的提示框。提示始终显示请求者(智能体和会话)、条目名称、智能体陈述的原因,以及一个可编辑的允许主机列表,因此您对凭证可在何处使用拥有最终决定权。如果该名称已存在,提示会明确说明,并显示该条目最后更新的时间和更新者。提交将替换已存储的值。Gateway 会原样保留提交的值,包括前导或尾随空格。Web、TUI 和 Apple 的请求字段均为单行。多行凭证请使用 CLI 的 --value-file 输入。
连接至 Gateway 的 TUI 也通过掩码输入接受请求:键入的字符显示为圆点,且绝不会进入聊天日志或输入历史。提示显示条目名称、原因和提议的允许主机。主机列表在 TUI 中为只读。提交即接受所显示的列表。如果您需要在提交前编辑它,请使用 Control UI。Skip(跳过) 会拒绝该请求。Esc 会使其保持待处理状态,/question 会重新打开它。切勿在普通输入区中输入凭证。
本地模式(openclaw chat 或 openclaw tui --local)无法完成与密钥存储绑定的请求。智能体会收到一个阻塞提示(blocker),指示操作员运行 openclaw secrets store,或在使用中的 Gateway 上使用 Control UI。本地提问提示支持掩码输入,但仅凭这一点并不能提供 Gateway 的密钥存储写入和运行时刷新流程。
如果智能体省略了主机提议,替换请求会以条目当前的主机列表开始。新条目以空列表开始。显式提交的空提议将保持为空。提交会保存所显示的列表或您的编辑,即使提示待处理期间另一次写入更改了该条目。清空列表会禁用出站替换,同时仍允许通过配置 SecretRef 使用该凭证。
一旦存储写入提交,请求即被视为已应答,无法再次提交。后续的运行时刷新失败不会撤销该写入:请解决所报告的提供程序(provider)错误并运行 openclaw secrets reload,而不是重新提交。
同一个工具结果会在一次后续元数据读取中报告 status: "stored"、SecretRef 和 currentPolicy。这是条目当前的主机列表,您可以编辑;它不是 Gateway 配置,也不是不可更改的审批回执:另一次写入可能已对其做了更改。available 包含完整的允许主机列表。空列表表示无出站。如果序列化后的列表超过 512 个字符,omitted 仅报告 allowedHostCount。missing、kind_changed 和 unavailable 分别表示条目已消失、变成了 env 条目,或没有完整且经过验证的主机策略。这些情况都不会撤销已保存的结果,也不意味着需要重新提交。当完整列表不可用时,智能体必须报告当前主机列表而非其提议,并且不得对主机做出任何断言。出现差异并不能解释谁以及为何更改了主机,也不能成为建议更改 Gateway 配置的理由。
Warning
允许主机管控的是 Gateway 的出站替换,而非配置 SecretRef。仅保留应接收该凭证的确切主机。空列表可阻止出站替换,但仍允许受支持的配置字段解析已存储的凭证。出站还要求启用代理。切勿通过将明文放入命令、参数、URL、日志或聊天中,来绕过缺失的代理或目标权限。
跳过提示或让其过期,会告知智能体没有凭证到达(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 凭据。
存储条目是常规的共享存储条目(参见 Secrets 管理):
- 在任意接受 SecretRef 的地方使用返回的完整
ref(提供方 API 密钥、频道令牌)。使用默认存储别名时,它是{ "source": "store", "provider": "default", "id": "STRIPE_API_KEY" }。secrets.defaults.store选择不同的提供方别名。写入会触发受影响的配置和 auth-profile 引用的刷新。成功的刷新还会替换已准备的模型状态,因此之后的目录读取会为已在智能体模型作用域内的提供方使用新凭据。 env条目是可读值。它们由操作员设置,而非凭据请求流程设置。secret条目仅在启用出站代理(secrets.egressProxy.enabled)时,才会以自动注入的不透明环境哨兵值形式出现在 Gateway 宿主子进程流量中。该变量使用存储条目的名称。从命令进程继承的环境中读取它。不要提供 secret 模板、覆盖该变量或打印它。替换要求目标与条目的允许主机匹配。禁用代理后,受保护条目不会被注入。请改用受支持的配置 SecretRef。原生 harness shell、沙箱和节点执行不会接收到这些受保护值。提供方故障排查开关OPENCLAW_SECRET_SENTINELS=off不会禁用受保护存储的密封。
受保护条目不会向子进程提供 SSH 或 sudo 密码,包括 sshpass 环境变量或 sudo -S 标准输入。出站代理会在出站 HTTPS 请求中替换凭据;允许的 SSH 主机不会启用 SSH 密码认证。${secret:NAME} 不是 exec shell 替换语法。在请求凭据之前,请检查是否存在受支持的消费者。
对于明确希望 Gateway 命令接收明文的操作员,openclaw secrets store set 支持带掩码输入的 --kind env 或 --value-file。此类条目可通过 secrets list 和 Gateway exec 被智能体读取;它们不保留受保护密钥的保密承诺。请使用继承的变量,而不是将它的值复制到命令中。沙箱、节点和原生 harness shell 执行不会接收存储环境条目。
Gateway 宿主 exec 在一次运行中的首次执行时捕获一份存储快照。在该时间点之前存储的凭据可以被包含。之后的新增、替换、删除和宿主编辑不会刷新该运行的快照。启动新的运行以观察这些更改。成功的凭据请求并不保证已在运行的 exec 工具能使用新值。
每个受管理的命令都会从该快照获得自己的代理授权。后台命令在发起回合结束后仍保留访问权限。进程退出、取消、超时或 Gateway 关闭会撤销授权并关闭其连接;其他命令保留自己的授权。已经交给上游传输的字节无法收回。
相关¶
- Ask user — 用于非凭据决策的结构化问题。凭据永远不是其有效答案。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw