| name | rotate-secrets |
| description | Guided secret rotation with validation. Never revoke old key before new one is verified.
Triggers: "rotate key", "change API key", "new token", "credential expired", "401 error".
|
Rotate Secrets
MANDATORY: Follow all 7 steps. Never revoke the old credential before the new one is verified working.
Step 1: Identify the Credential
Ask Trent which credential needs rotating, or determine from error logs. Reference table:
| Credential | What It's For | Where to Get a New One |
|---|
| ANTHROPIC_API_KEY | Primary AI model | console.anthropic.com > API Keys |
| OPENAI_API_KEY | Fallback AI model | platform.openai.com > API keys |
| GEMINI_API_KEY | Fallback AI model | aistudio.google.com > Get API key |
| TELEGRAM_BOT_TOKEN | Agent messaging | BotFather on Telegram > /mybots > API Token |
| GITHUB_TOKEN | Memory sync | github.com > Settings > Developer settings > Personal access tokens |
| BRAVE_API_KEY | Web search | brave.com/search/api > Dashboard |
| SERPAPI_KEY | Search results | serpapi.com > Dashboard > API Key |
| PERPLEXITY_API_KEY | AI search | perplexity.ai > Settings > API |
| SHOPIFY_UK_ACCESS_TOKEN | UK store data | Shopify Admin (UK) > Apps > Custom apps |
| SHOPIFY_US_ACCESS_TOKEN | US store data | Shopify Admin (US) > Apps > Custom apps |
| SHOPIFY_AU_ACCESS_TOKEN | AU store data | Shopify Admin (AU) > Apps > Custom apps |
| META_ADS_ACCESS_TOKEN | Meta ad data | Meta Business Suite > System User > Generate Token |
| POLAR_API_KEY | Analytics | Polar Analytics dashboard > Settings > API |
| NVIDIA_API_KEY | AI model | build.nvidia.com > Settings > API Keys |
Step 2: Generate New Credential
Guide Trent through the provider's dashboard:
- Tell him exactly which page to navigate to
- What buttons to click
- What to name the new key (if applicable)
- What permissions/scopes to select
IMPORTANT: Do NOT revoke the old credential yet. We need it as a fallback.
Step 3: Backup Current .env
ssh -i ~/.ssh/id_ed25519_github root@72.62.213.231 \
"cp ~/.openclaw/.env ~/.openclaw/.env.backup-$(date +%Y%m%d-%H%M%S)"
Tell Trent: "Backed up the current secrets file. If the new key doesn't work, we can restore."
Step 4: Update the VPS
Ask Trent to paste the new credential value. Then update the .env file.
Option A (if Trent is comfortable with nano):
ssh -i ~/.ssh/id_ed25519_github root@72.62.213.231 "nano ~/.openclaw/.env"
Guide him: "Find the line that says [CREDENTIAL_NAME]=, delete the old value, paste the new one, then Ctrl+O to save and Ctrl+X to exit."
Option B (safer, using sed):
ssh -i ~/.ssh/id_ed25519_github root@72.62.213.231 \
"sed -i 's|^CREDENTIAL_NAME=.*|CREDENTIAL_NAME=NEW_VALUE|' ~/.openclaw/.env"
After editing, verify permissions are still correct:
ssh -i ~/.ssh/id_ed25519_github root@72.62.213.231 "chmod 600 ~/.openclaw/.env"
Step 5: Restart and Validate
ssh -i ~/.ssh/id_ed25519_github root@72.62.213.231 "systemctl restart openclaw-gateway"
Wait 15 seconds, then check health:
ssh -i ~/.ssh/id_ed25519_github root@72.62.213.231 "openclaw gateway health"
Check logs for the specific provider:
ssh -i ~/.ssh/id_ed25519_github root@72.62.213.231 \
"journalctl -u openclaw-gateway --since '2 min ago' --no-pager | grep -i [PROVIDER_NAME]"
If health check passes and no auth errors in logs, the new credential is working.
Step 6: Revoke Old Credential
ONLY after the new credential is verified working:
Tell Trent: "The new key is working. Now go back to [provider dashboard] and delete the old key. If the agent breaks in the next few minutes, we have the backup from Step 3."
Step 7: Update Rotation Log
Remind Trent to update docs/CREDENTIAL-ROTATION.md in the kurk-org repo with:
- Credential name
- Today's date
- Who rotated it
Special notes:
- SERPAPI: Both
SERPAPI_KEY and SERPAPI_API_KEY must be set to the same value (the ClawdHub skill expects the second form)
- TELEGRAM_BOT_TOKEN: After rotating, the old bot token is immediately invalidated. Have the new one ready before changing.
- GITHUB_TOKEN: Must have
repo scope for memory sync to work
Rules
