Secrets Tool: Request Credentials Without Exposing Them

secrets requests a credential from you without exposing it to the agent. The agent identifies an entry by name, you enter the value into a trusted prompt, and the Gateway stores it directly in the shared secret store. The value stays out of the chat, the session transcript, the tool result, and the model's context; the agent only knows the entry exists.

Only the main session has access to this tool. Subagents and other non-primary runs do not receive it.

It is on by default and follows the standard tool policy, with no separate config key. To disable it, deny it as you would any other tool (for instance tools.deny: ["secrets"] in openclaw.json); allowlists and tool profiles treat it identically.

Actions

• request, request a credential from the human and save it under a name like STRIPE_API_KEY. Requests are restricted to protected secrets: an env value is accessible via list, so requesting one would undermine the masked prompt's guarantee. The agent can suggest allowedHosts and a brief reason shown on the prompt, and the tool waits until you respond, skip, or it times out (15 minutes by default). The request ties to the requesting agent run; if that run finishes before you answer, the write is rejected.
• list, entry metadata: name, kind, allowed hosts, and last update. Secret values are structurally omitted from the listing. Operator-set env entries display their value, since those are injected into exec environments anyway and are readable by the agent by design.
• delete, soft-delete an entry by name. Deleted entries are purged after 30 days.

No action writes a value supplied by the agent, deliberately. If a value needs to enter the store, it comes through the human prompt, the /settings/secrets page, or the openclaw secrets store CLI.

Answering a request

The web Control UI places the prompt above the composer with a masked input. The prompt always shows who is asking (agent and session), the entry name, the agent's stated reason, and an editable list of allowed hosts, so you decide where the credential can be used. If the name already exists, the prompt notes it and shows when and by whom the entry was last updated; submitting replaces the stored value.

Warning

Keep at least one allowed host. A secret with no allowed hosts is stored but never substituted at egress, so the request appears to succeed while the credential is unusable. Narrow the list instead of clearing it.

Skipping the prompt, or letting it expire, tells the agent that no credential arrived; it proceeds with best judgment rather than failing the turn.

iOS, macOS, and Android show the same card with a masked secret field.

Chat channels never accept the value. On Telegram, Discord, and similar surfaces the request arrives as a link to the Control UI prompt; typing a credential into a chat message is exactly what this flow avoids, so a plain-text reply is not treated as an answer.

Creating a credential request requires an operator.admin client (the agent's own Gateway client qualifies) and is bound to the requesting agent run. Answering requires only the normal question scope, because answering provides a value rather than reading one.

Using a stored credential

A stored entry is a regular shared-store entry (see Secrets management):

• Reference it from config as { "source": "store", "id": "STRIPE_API_KEY" } wherever a SecretRef is accepted (provider API keys, channel tokens). Writes refresh affected config references automatically.
• env entries are injected into gateway-host exec environments starting with the next agent run.
• secret entries are substituted into subprocess traffic only when the egress proxy is enabled (secrets.egressProxy.enabled) and the destination matches the entry's allowed hosts; otherwise the agent and its subprocesses see only an opaque placeholder.