.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
By default, OpenClaw stores API keys and bot tokens in plaintext inside ~/.openclaw/openclaw.json and related credential files. For local personal use, that's probably fine. For anything running on a VPS, shared with others, or connected to services that cost real money, it's a genuine risk. Exposed tokens have caused bill spikes from stolen API keys, channel hijacks via leaked Telegram and Discord tokens, and data exfiltration through agents with read/write tool access.
The good news is OpenClaw has a native secrets management system built in that most people never configure, because the onboarding flow doesn't require it. This guide covers the full picture: where secrets currently live, how to move them out of plaintext config, integrating with external secret stores, rotating credentials safely, and detecting leaks before they cause damage.
How your secrets end up exposed
Understanding the attack surface makes the mitigations easier to prioritize. There are a few common ways OpenClaw credentials get exposed in practice, and they're mostly not dramatic hacks.
Git commits. Someone puts their ~/.openclaw/ directory under version control or copies openclaw.json into a repo for backup purposes. Even a private repo is one misconfigured permission setting away from being public. Pre-commit hooks that scan for token patterns catch this, but most people don't have them.
Backup archives. The standard backup advice is to tar up ~/.openclaw/. An unencrypted tar sitting on an S3 bucket or transferred over an unencrypted connection contains every token you have in plaintext. The upgrade guide recommends encrypting backups with GPG for exactly this reason.
Debug logs. Running the Gateway at debug log level is the right move for troubleshooting. It's also a way to get API keys into log files if environment variable resolution logging is verbose. Check that your log files don't contain raw token values before sharing them anywhere.
MEMORY.md. This one is less obvious. If an agent is prompted (intentionally or via injection) to write its configuration context into memory files, tokens from its auth profile can end up in MEMORY.md. This is a prompt injection risk more than a config risk, but the consequence is the same: plaintext tokens in a file that might get backed up, synced, or indexed somewhere.
World-readable files. Fresh installs on Linux sometimes leave ~/.openclaw/ with permissions that any user on the system can read. On a shared VPS or any multi-user system, this is a straightforward credential leak.
Environment variables and .env files
The first step up from plaintext config is moving tokens to environment variables. OpenClaw resolves ${VAR} references in config strings at startup, and reloads them atomically when the Gateway restarts. This means you can keep the structure of your config while removing the actual values from it.
The .env loading order
OpenClaw looks for environment variable values in this order, with earlier sources taking priority:
- Process environment (set by systemd, Docker, or the shell that launched the Gateway)
.envin the current working directory~/.openclaw/.env(the daemon's own env file)- An inline
envblock in the config itself
For most setups, ~/.openclaw/.env is the right place to put secrets. It stays close to the config it supports, it's not in a working directory that might get version controlled, and it's easy to reason about. A basic example:
ANTHROPIC_API_KEY=sk-ant-...
TELEGRAM_BOT_TOKEN=123456:ABC-...
DISCORD_BOT_TOKEN=...
OPENAI_API_KEY=sk-...Then in your config, reference them:
models:
providers:
anthropic:
apiKey: ${ANTHROPIC_API_KEY}
channels:
telegram:
token: ${TELEGRAM_BOT_TOKEN}File hygiene for .env
The .env file itself needs to be protected. Permissions first:
chmod 600 ~/.openclaw/.env
chown youruser:youruser ~/.openclaw/.envIf you have anything in ~/.openclaw/ under version control (skills, custom tools, workspace templates), make sure .env is in .gitignore. A pre-commit hook that scans for obvious token patterns is worth adding to any repo that touches OpenClaw config:
# Install truffleHog or gitleaks as a pre-commit hook
pip install pre-commit
# Or: brew install gitleaksFor systemd service deployments, avoid loading the .env file through a shell that inherits the daemon's environment into child processes. Use systemd's EnvironmentFile directive instead, which loads the file directly without shell interpolation:
[Service]
EnvironmentFile=/secure/path/openclaw.envKeep that file outside of ~/.openclaw/ if you're on a shared server and restrict its permissions to the service user.
OpenClaw's native SecretRef system
Moving from plaintext to environment variables is a good first step. The full solution is OpenClaw's SecretRef system, which lets you define named secret providers and reference secrets by ID rather than value anywhere in your config. The Gateway resolves the references at startup and fails fast if any are unresolvable, which means misconfigured secrets surface immediately rather than causing runtime failures.
Provider types
There are three built-in provider types: env, file, and exec. Each covers a different deployment scenario.
env provider reads from environment variables with an optional allowlist to restrict which variables can be accessed:
secrets:
providers:
default:
source: "env"
allowlist:
- "ANTHROPIC_*"
- "TELEGRAM_*"
- "DISCORD_*"file provider reads from a JSON file or a file containing a single value. Useful when you want to keep secrets in a location managed separately from your OpenClaw config:
secrets:
providers:
key_file:
source: "file"
path: "/secure/openclaw-keys.json"
mode: "json"The JSON file format is straightforward: keys are the secret IDs you'll reference, values are the actual secrets.
exec provider runs a command and uses its stdout as the secret value. This is what enables integration with external secret managers:
secrets:
providers:
onepassword:
source: "exec"
command: "/opt/homebrew/bin/op"
allowSymlinkCommand: true
trustedDirs:
- "/opt/homebrew"
args: ["read", "op://Personal/OpenClaw/anthropic_key"]Referencing secrets in config
Once providers are defined, you reference secrets in config using a keyRef object instead of a literal value:
profiles:
main:
type: "api_key"
keyRef:
source: "env"
id: "ANTHROPIC_API_KEY"
telegram_prod:
type: "bot_token"
keyRef:
source: "exec"
provider: "onepassword"
id: "telegram_prod_token"If you have an existing setup with plaintext tokens in auth-profiles.json, OpenClaw provides a migration command that scrubs them and rewrites the file to use references:
openclaw secrets configure --skip-provider-setupIntegrating external secret stores
The exec provider is the bridge to any external secret manager. The pattern is always the same: configure the provider to call the external tool's CLI, and reference secrets by their path or ID in that store.
HashiCorp Vault
secrets:
providers:
vault:
source: "exec"
command: "vault"
args:
- "kv"
- "get"
- "-field=token"
- "secret/openclaw/anthropic"This assumes the Vault CLI is installed and authenticated (via VAULT_TOKEN or a Vault agent). The Gateway process needs to be able to reach Vault at runtime, which means either running Vault locally or ensuring network access from wherever the Gateway runs.
AWS Secrets Manager
secrets:
providers:
aws_secrets:
source: "exec"
command: "aws"
args:
- "secretsmanager"
- "get-secret-value"
- "--secret-id"
- "openclaw/anthropic"
- "--query"
- "SecretString"
- "--output"
- "text"The AWS CLI needs credentials to authenticate, ideally via an IAM role attached to the EC2 instance or ECS task rather than static access keys. The IAM policy should grant only secretsmanager:GetSecretValue on the specific secret ARNs that OpenClaw needs, nothing broader.
1Password CLI
secrets:
providers:
onepassword:
source: "exec"
command: "op"
allowSymlinkCommand: true
trustedDirs:
- "/usr/local/bin"
- "/opt/homebrew/bin"
args:
- "read"
- "op://Personal/OpenClaw API Keys/anthropic"The allowSymlinkCommand: true and trustedDirs settings are security constraints that prevent the exec provider from being redirected to arbitrary commands. Only commands in trusted directories can be executed as providers, which matters because an exec provider with a tampered command path is a code execution vulnerability.
Bitwarden / BWS
secrets:
providers:
bitwarden:
source: "exec"
command: "bw"
args:
- "get"
- "password"
- "OpenClaw Anthropic Key"Bitwarden Secrets Manager (BWS) also works and is worth considering if you want a purpose-built secrets tool rather than a password manager.
Docker and Kubernetes secrets
For containerized deployments, use the file provider pointing at the mounted secrets path. Docker Swarm and Kubernetes both mount secrets at /run/secrets/ by default:
secrets:
providers:
container_secrets:
source: "file"
path: "/run/secrets/anthropic_key"
mode: "singleValue"This works cleanly with Docker Compose's secrets: block and Kubernetes Secret volumes. See the clustering guide for how secrets fit into a multi-replica Kubernetes deployment.
Rotating credentials
Rotating a compromised or expired credential is stressful if you've never done it on a running system. Doing it in advance, on a schedule, removes most of that stress because you've already tested the process.
The sequence for a clean rotation:
- Generate the new key in the provider's dashboard (Anthropic console, Telegram BotFather, Discord developer portal, etc.). Don't revoke the old one yet.
- Update the secret store with the new value. For env-based secrets, update
~/.openclaw/.env. For external stores, update the secret value there. - Test resolution without restarting the live Gateway:
openclaw secrets listshows masked values and confirms the provider can resolve each reference. - Restart the Gateway to pick up the new value atomically. The Gateway fails fast at startup if any secret is unresolvable, so a misconfigured rotation surfaces immediately before traffic hits the new credential.
- Verify connections with
openclaw channels status --probeto confirm each channel authenticates with the new token. - Revoke the old key only after confirming the new one works. This is the step people skip when they're in a hurry and then regret.
Least privilege per integration
Using a single API key for everything is convenient and dangerous. If that key leaks, every integration is exposed simultaneously. The better approach is separate keys per integration and per agent, scoped to the minimum permissions each one actually needs.
In practice this means: one Anthropic key for your main agent, a separate one for background cron agents (possibly on a restricted tier), per-channel bot tokens for Telegram and Discord, and separate OAuth credentials for Gmail and Google Calendar integrations. See the Gmail integration guide and Slack integration guide for how to scope OAuth credentials to specific permissions rather than full account access.
For agents running in public channels with untrusted input, deny exec and webhook tools in the tool allow/deny configuration even if the agent's API key has broader permissions. Defense in depth: the token shouldn't be scoped broadly, and the tool access shouldn't be either.
Auditing for leaks
OpenClaw includes a secrets audit command that scans known credential locations for plaintext tokens:
openclaw secrets audit --checkThis checks auth-profiles.json, legacy auth.json files, and other locations where plaintext tokens commonly end up. Run it after any config change and after upgrades, since upgrades sometimes generate new credential files in the old plaintext format.
Beyond the native audit, a few external tools are worth adding to your workflow:
- truffleHog or gitleaks as pre-commit hooks on any repo that touches OpenClaw config. These scan for high-entropy strings and known token patterns before they can be committed.
- Manual grep of log files if you've run at debug log level:
grep -r "sk-ant\|sk-\|Bearer" ~/.openclaw/logs/. Token values appearing in logs is a sign that something in the resolution or logging pipeline is more verbose than it should be. - Permission audit on backup files: any
.tgzbackup containing~/.openclaw/should be encrypted. Check that you didn't create any unencrypted archives during troubleshooting sessions and forget to delete them.
For OTEL-based monitoring, OpenClaw redacts secret values from traces and logs by default. If you're seeing token values appearing in Datadog or Grafana traces, check whether a custom skill or tool is logging environment variables explicitly.
The security best practices guide covers the broader operational security picture beyond secrets specifically.
