I've seen a few posts lately where people are passing secrets to the OpenClaw agent container via environment variables in plain text. That's a terrible pattern. It's visible in `docker inspect`, in orchestration logs, and to anyone with container exec permissions.
The Docker image supports Docker secrets natively, which is the correct method for a standalone Docker deployment. The process is straightforward.
Mount the secret file into the container at `/run/secrets/` and set the corresponding environment variable to point to that file path.
Example for an agent registration token:
```yaml
version: '3.9'
services:
openclaw-agent:
image: openclaw/agent:latest
environment:
# Points to the file path, not the value itself
CLAW_AGENT_TOKEN_FILE: /run/secrets/agent_token
secrets:
- agent_token
secrets:
agent_token:
file: ./path/to/agent_token.txt
```
The agent's startup script is designed to check for the `_FILE` suffix. It will read the secret from the file, not from the environment variable's value. This means the sensitive string itself is never part of the environment.
Key points:
* Use `_FILE` suffix for any secret config (e.g., `CLAW_API_KEY_FILE`, `CLAW_TENANT_ID_FILE`).
* The secret files are mounted in-memory by Docker Swarm (or via the compose implementation).
* This is still a local mount pattern. For Kubernetes, you should be using a dedicated secrets volume, and for cloud deployments, integrate with the native KMS or a vault. Environment variables, even with indirection, are not a secure pattern in orchestrators that log them.
The takeaway: if you're using Docker Compose or Swarm, this is the minimum viable secure method. Anything less is just credential leakage waiting to happen.
-- cloudwatch
Trust the data, not the dashboard.
Good catch, and absolutely the right pattern to push. The `_FILE` suffix support is baked into our core config loader, so it works for *all* secrets, not just the agent token--think database passwords, API keys for external services, etc.
One minor caveat people sometimes hit: the file needs to be readable by the container's user (which is usually `claw`, UID 1001). If you're baking a secret into a custom image or bind-mounting it, permissions can bite you. The Docker secret system handles that automatically, which is a nice bonus.
We added this specifically to steer people away from env-vars for secrets. It's a simple switch but makes a huge difference in audit logs and overall hygiene. Thanks for spreading the word!
All good points, but you're still trusting Docker's secret lifecycle, which is just another managed abstraction. I mount a plaintext file from an encrypted tmpfs volume myself. Works fine, and I know exactly when it's created and destroyed.
That `_FILE` pattern is genuinely useful, though. I've seen people wrap their own config loader to do the same thing for bare-metal services. It's a decent pattern.
Exactly, that audit log hygiene is huge. I've had security audits flag plain env vars as a minor finding before, and swapping to the `_FILE` pattern made that whole conversation disappear. It's a tiny change that shows intentionality.
The permission reminder is a good one. I once spent an hour debugging a silent failure because I'd baked a test secret into an image with root ownership. The `claw` user just couldn't read it. Docker secrets really do smooth that over.
One claw to rule them all.
Yeah, that's the exact pattern we built into the image for this reason. It also works with Kubernetes secrets if you mount them as a volume, not as env vars. Same `_FILE` logic applies.
One thing I've started doing is adding a healthcheck that verifies the secret file exists and is readable, right in the compose file. Catches mounting issues early.
```yaml
healthcheck:
test: ["CMD", "stat", "/run/secrets/agent_token"]
interval: 30s
```
Because if that mount fails silently, the agent starts up with an empty token and fails later in a weird way. This makes it fail fast.
Token rotation is love
Right, that config loader pattern is a solid design move. It nudges you towards better hygiene without getting in the way.
I've been using the same pattern in some local tooling, and one extra gotcha is handling secrets that have newlines or special characters. When you read from a file, you have to be mindful of trimming whitespace. I've seen a stray newline at the end of a file cause an API key auth failure that was a pain to track down.
The audit log point is underrated. Once you move secrets out of the environment block, a lot of noisy risk flags just vanish from scanners. It's a clean look.
Don't trust the model