Secret Rotation#
📌 TL;DR#
- Rotate keys if they're accidentally exposed, you share your Pi, or see unexpected charges.
- Update keys in
~/.openclaw/secrets/*.envfiles and viaopenclaw configurefor Telegram. - Always test the agent after a change, then revoke the old key.
- Use the full pre-publish checklist for a comprehensive rotation.
🎯 Why Rotate?#
API keys stored on disk could be recovered if your system is compromised. Prompts and data transit the provider's servers. Regularly rotating credentials limits the blast radius if a key is leaked. Rotate immediately if you: accidentally commit a key to git, share physical access to your Pi, or notice unexpected charges on your provider account.
📋 What to Rotate#
The table below lists all credentials in a standard OpenClaw setup.
| Secret | Location | Used By |
|---|---|---|
| Anthropic API Key | ~/.openclaw/secrets/anthropic.env | Jarvis, Mr. Stark |
| OpenRouter API Key | ~/.openclaw/secrets/openrouter.env | Sherlock, Shakespeare |
| Brave Search API Key | ~/.openclaw/secrets/brave.env | Sherlock |
| Telegram Bot Token | Encrypted in ~/.openclaw/openclaw.json | OpenClaw Gateway |
| Mission Control Internal Token | ~/.openclaw/secrets/mc-internal.env (if present) | Mission Control API |
| Pi OS User Password | System (via passwd command) | SSH & system access |
🔧 How to Rotate (Short Version)#
Follow these steps for each key:
- Generate a new key: Log into the provider's console (e.g., Anthropic, OpenRouter) and create a new API key or token.
- Update the local secret:
- For
.envfiles:nano ~/.openclaw/secrets/<provider>.env, replace the key, save, and ensurechmod 600. - For the Telegram token: Use
openclaw configureor edit~/.openclaw/openclaw.jsondirectly (not recommended).
- For
- Smoke-test: Ask Jarvis to test the affected agent (e.g.,
"Jarvis, quick test Sherlock with a simple search."). - Revoke the old key: Once confirmed working, revoke the old key in the provider's console to deactivate it.
📖 Full Runbook#
The steps above cover a single key. For a comprehensive, pre-publish rotation covering every credential and dependency end-to-end, see the detailed checklist: writing/projects/pre-publish-secret-rotation-checklist.md.
📅 Routine Cadence#
- Before sharing your Pi or making any project content public (e.g., a blog post).
- Quarterly as a security baseline.
- Immediately after any suspected leak or exposure.
💬 Ask Jarvis to Remind You#
You can have Jarvis remind you when it's time for the next rotation.
💬 Try this
"Jarvis, remind me in 90 days to rotate my OpenClaw secrets."
✅ What you should see Jarvis will confirm and schedule a reminder job in the OpenClaw cron scheduler. When the time comes, you'll receive a Telegram prompt.