OpenClaw secrets: Protected secret or Agent-readable environment?

Stored is not the same as connected

A credential has two separate jobs: being kept somewhere and reaching the connection that needs it. In OpenClaw, a protected store entry can supply a supported configuration field through a SecretRef. An enabled egress proxy can also substitute a protected value into a request to an approved destination. Neither happens just because the entry exists.

That distinction matters when an agent writes its own integration. In a September 2026 walkthrough with OpenClaw 2026.9.4, saving an API key and a mail password as protected secrets did not give an ordinary script the plaintext credentials it expected. The useful question was not whether the password had been saved. It was how that particular connection would receive it.

Which kind should you choose?

• An OpenClaw configuration field: start with a protected secret. Establish that the field accepts a SecretRef and that the active configuration references this entry.
• A request through the secret-substituting proxy: start with a protected secret. The proxy must be enabled and the credential bound to the intended destination.
• A custom program that needs the raw value: use an agent-readable environment entry if that access is appropriate. Establish that the program runs in an environment that receives the entry.

The secrets operations reference places these choices in the Control UI under Settings → Secrets. Pick the kind deliberately when adding the value. Changing its name or repeatedly re-entering it will not change the access mode.

Why an environment value may still be missing

The current store and egress reference says agent-readable entries are injected into Gateway-host execution. They are not a universal environment shared by native Codex shell tools, ACP processes, sandbox execution and connected nodes. Establish where the failing command runs before changing the credential.

The same reference describes a per-run environment snapshot. If a command already ran before you saved the value, begin a new run before testing again. A saved edit and an already-running command can legitimately see different state.

If the agent reports an oc-sent- value, do not ask it to reveal the underlying secret. The placeholder is useful only along the supported substitution path. Sending it directly to a service that expects a password will not authenticate.

Test access without printing the key

Enter credentials through the masked secret-entry flow, not an ordinary chat message. OpenClaw’s secrets tool can request a protected value through that flow without putting the value in the model’s conversation. It does not make agent-readable entries equally private: a program with the plaintext can print, transmit or save it.

Ask for a small authenticated operation and its result: whether the service accepted the connection, which account it recognized, or whether a permitted read succeeded. Avoid environment dumps and commands that list credential values. In the same 2026.9.4 walkthrough, listing an agent-readable entry put its value into the transcript. The credential was revoked afterward; clearing the terminal would not have revoked it.

A useful request is:

Check whether this connection can authenticate. Do not print credentials or list the environment. Tell me which service accepted the connection and whether the requested access worked.

A package-install 403 can be a different problem

If an error explicitly says a host is not in the egress proxy’s allowed hosts, another password attempt is not the fix. A configured secrets.egressProxy.allowedHosts list can restrict traffic as well as credential destinations. The egress reference distinguishes the traffic allowlist from the hosts bound to a secret.

Confirm that the blocked host is the package source you intended to contact, then adjust that traffic permission narrowly if you administer the Gateway. A package download does not need permission to receive your mail password. Keep those two decisions separate.