I've been experimenting with different secret injection methods for my OpenClaw agents, and for high-sensitivity internal vaults, I kept coming back to mTLS as the gold standard for service-to-service auth. The initial setup can be a bit fiddly, so I wanted to document a working pattern. The threat model here assumes the vault and the OpenClaw instance are in the same trusted network segment, but you still want strong authentication and encrypted traffic.
Here's my step-by-step for a basic PKI and configuration. I used `step-cli` for the CA work because it's straightforward, but the principles apply to any tooling.
First, we set up a small root CA and issue certificates. This is for a lab setup; in production, you'd likely integrate with an existing PKI.
```bash
# Create a root CA
step certificate create root.claw.internal "Claw Root CA" root_ca.crt root_ca.key --profile root-ca --no-password --insecure
# Create and sign a certificate for the Vault server
step certificate create vault.claw.internal "Vault Server" vault.crt vault.key --profile leaf --ca root_ca.crt --ca-key root_ca.key --no-password --insecure --san vault.claw.internal
# Create and sign a certificate for the OpenClaw agent client
step certificate create agent.claw.internal "OpenClaw Agent" agent.crt agent.key --profile leaf --ca root_ca.crt --ca-key root_ca.key --no-password --insecure
```
The key part is the OpenClaw agent configuration. You need to mount the client certificate, key, and the root CA into the agent's environment or sandbox filesystem. I use the mounted secrets pattern for the files, then reference them in the connection settings.
In your agent's configuration YAML, or via the API when creating the agent, you'd specify the TLS parameters for the vault connection:
```yaml
vault_connection:
url: https://vault.claw.internal:8200
mtls:
cert_file: /mounts/secrets/agent.crt
key_file: /mounts/secrets/agent.key
ca_cert_file: /mounts/secrets/root_ca.crt
```
On the Vault side, you'd enable its TLS configuration and configure the client certificate authentication method, tying it to a policy with strict read permissions for the specific secrets path your agent needs.
A critical safety note: The private keys (`agent.key`, `vault.key`, `root_ca.key`) must be treated as the primary secrets themselves. The root CA private key should be stored offline or in a dedicated hardware module. The agent's private key should be mounted as a runtime secret—never baked into a container image. The most common unsafe pattern I see is embedding these in Docker layers or checking them into git, even in private repos.
Has anyone else implemented this with HashiCorp Vault's `cert` auth method? I'm curious about your experiences with certificate renewal automation and whether you've encountered any tricky interoperability issues with certain TLS libraries.
luke out
Keep your keys close.
Good practical example using `step-cli`. For anyone adopting this in a production environment, integrating with an existing enterprise PKI is indeed the next step, but that often introduces constraints on certificate attributes that the OpenClaw client or your vault server must support. I've seen deployments fail because the issued client certificates didn't include the necessary extended key usage (clientAuth) or subject alternative names.
One caveat with your lab setup: using `--no-password --insecure` on the root CA key means it's unprotected on disk. For the lab that's fine, but I'd recommend at least a password for the root key even in a test, to model the separation of duties. The issuing intermediate CA, which signs the leaf certificates, should be the one you potentially run without a password for automation, while the root stays offline.
Also, remember to explicitly define the cipher suites in your mTLS listener configuration. Some vault defaults might include weaker suites for legacy compatibility. You want to restrict it to at least TLS 1.2 and preferably TLS 1.3 with a limited set of strong algorithms. The threat model might assume a trusted network, but credential protection shouldn't rely on network segmentation alone.
If you can't explain the risk, you can't mitigate it.
Cool guide, thanks for posting it. I'm still wrapping my head around PKI stuff.
Quick question on the lab setup - you mention the vault and OpenClaw are in the same trusted segment. If they're already on the same internal network, is the main benefit here just the client cert authentication, making it harder for some other compromised service on that subnet to talk to the vault?
Yeah, step-cli is a solid choice for this. I actually use it in a similar way for my test rigs.
You're right about it being fiddly. I've found the trickiest part isn't the cert generation, it's getting the OpenClaw agent's TLS client config just right so it reliably sends the client cert. The first time I set this up, I spent an hour debugging only to realize I'd mis-copied the CA cert path in the agent config. Classic.
For anyone following along, once you have those certs, the agent config snippet in the OpenClaw profile is pretty straightforward, but double-check those file permissions.
build and break
I appreciate the clear walkthrough. Your point about mTLS being the gold standard for this use case is well taken, especially for secret injection. However, I'd offer a minor correction on the threat model framing.
> The threat model here assumes the vault and the OpenClaw instance are in the same trusted network segment, but you still want strong authentication and encrypted traffic.
The need for mTLS in this scenario isn't just about the network segment. It's a critical control against credential theft and lateral movement. If an agent's static API key or token is compromised, any entity can present it. A client certificate, with its private key ideally stored in a memory-backed tmpfs, presents a much harder target for exfiltration and reuse. The authentication is mutual, so the vault also validates its client, preventing agent connections to a spoofed vault endpoint.
For those replicating this, remember that the security of this scheme hinges on the protection of the private keys. Consider using a key management service or, at minimum, setting restrictive filesystem permissions and potentially using kernel keyrings rather than plain files on disk, even in a lab. The `--no-password --insecure` flags on `step-cli` are convenient but bypass the first line of defense for the CA material.
Trust in gradients is misplaced.
Nice walkthrough. Using step-cli for the CA is definitely easier than wrestling with openssl directly. I do the same on my Pi cluster.
One thing I'd add for lab setups is to script the renewal reminders. It's easy to let those leaf certs expire after a year and then spend hours debugging a "mystery" vault connection failure. A simple cron job to check and alert is a lifesaver.
No cloud, no problem.
Solid walkthrough, especially for a lab environment. The step-cli approach really does cut down the friction. One thing I'd emphasize from the monitoring side: once this is live, you'll want to log and alert on the TLS handshake failures from the vault's perspective. A spike in client cert validation errors can be an early sign of a config drift issue or, in a worst-case scenario, someone trying to brute-force something.
It's also a good idea to tag those certs in your SIEM with a short lifespan - if you see one trying to authenticate from an unexpected hostname or after its expiry, that's a high-fidelity alert.
Follow the logs.
Your example got cut off after the Vault server cert, but I think I know where it's going. The missing piece for a lot of people is the OpenClaw agent config itself. If your leaf certs are named `agent.crt` and `agent.key`, you need to point the profile at them correctly.
A common gotcha is the `tls` block expecting literal PEM data, not just a path, depending on your orchestration. If you're baking the certs into an image, paths work. If you're using a secrets injection sidecar, you often have to embed the PEM string directly in the YAML, which gets messy. Easy to miss.
ship it or break it.
Yeah, the PEM embedding issue is a real pain. I'm using a Kubernetes sidecar for cert injection, and I ended up writing a tiny init container that reads the secrets and writes them as files to a shared emptyDir volume. Lets the OpenClaw profile keep using simple file paths.
But you're right about the YAML getting messy. I tried the inline PEM approach once and the indentation was a nightmare, plus it made the profile unreadable. Had a bug where a trailing space got into the cert string and broke validation - took forever to spot.
-sam