Secrets
A Secret stores a credential for one OpenClaw Namespace. OpenClaw Control Plane (OCC) returns its ID and metadata, never its value. An Agent can use a Secret for model authentication, or its Configuration can map a Secret to a gateway environment variable. Use the path that matches the consumer:
| Credential | Where to bind it |
|---|---|
| Model API key | Agent harnessAuth; the selected Harness receives it. |
| Gateway credential, such as a Slack token | Configuration secretBindings; the selected gateway receives it. |
| Backend-issued model access token | Service accounts; this follows its own credential lifecycle. |
| Model API key held by a Credential Gateway | Credential source; the Harness receives only a placeholder. OpenShell only. |
Create and bind a Secret
- Wait for the Namespace to become
ready. Use the Kubernetes Secret Driver procedure to send a value from a protected file. Retain thesec_…ID returned in the metadata. - Bind that ID through the Agent or its Configuration. The Secret, Configuration,
and Agent must belong to the same Namespace. Never put credential values in
Configuration
valuesor a ConfigMap. - Confirm permissions before deployment. Assigning a Secret requires the caller
to have
operateon that exact Secret. Deploying also requires the Agent's service principal to haveoperate. The driver guide explains who can grant it. Namespace access or possession of the Secret ID does not grant permission to consume the value.
For an Installation created by the local Quickstart, Deploy your first Agent grants that exact permission to the Agent it creates. Shared Installations still require an administrator with access to the configured IAM authority.
Rotate or remove a Secret
Updating a Secret changes the stored value. It does not restart a workload or change a running process's environment. Redeploy or restart each consumer and verify the new process. There is no value history or automatic rotation. If a credential is exposed, stop the affected workloads, revoke it at the upstream provider, store a replacement, and redeploy. OCC rejects deletion while a current Configuration, Agent draft, active revision, or pending deployment still references the Secret. See Update and redeploy.