Secrets Management

Secrets Management

OpenClaw’s configuration file (openclaw.json) supports ${VAR} references that resolve from ~/.openclaw/.env at runtime. This keeps secrets out of git while maintaining a version-controlled config.

How It Works

config/openclaw.json          ~/.openclaw/.env
─────────────────────         ─────────────────
"apiKey": "${BRAVE_API_KEY}"  BRAVE_API_KEY=BSA_abc123...
"password": "${BB_PASSWORD}"  BB_PASSWORD=my-secret...

At gateway startup, OpenClaw reads ~/.openclaw/.env and substitutes ${VAR} references in the config. The repo config never contains actual secrets.

Environment Variables

All required variables are documented in config/.env.example:

Variable	Used By	How to Get It
BLUEBUBBLES_PASSWORD	BlueBubbles channel	Set in BlueBubbles Server settings
BRAVE_API_KEY	Web search tool	brave.com/search/api
OPENCLAW_GATEWAY_TOKEN	Gateway auth	Generate any strong random string
GEMINI_API_KEY	nano-banana-pro skill	aistudio.google.com
OPENAI_API_KEY	Whisper transcription	platform.openai.com
ELEVENLABS_API_KEY	TTS voice + SAG skill	elevenlabs.io

Initial Setup

cp config/.env.example ~/.openclaw/.env
chmod 600 ~/.openclaw/.env
# Edit ~/.openclaw/.env and fill in real values

Adding a New Secret

1. Add ${NEW_VAR} to the appropriate field in config/openclaw.json
2. Add NEW_VAR=actual-value to ~/.openclaw/.env
3. Add NEW_VAR=your-placeholder to config/.env.example (with a comment explaining where to get it)
4. Copy the updated config: cp config/openclaw.json ~/.openclaw/openclaw.json
5. Restart the gateway: openclaw gateway restart

Secrets Audit (secrets-audit.sh)

The scripts/secrets-audit.sh script verifies the entire secrets chain is intact. Run it anytime you change config or rotate tokens.

bash scripts/secrets-audit.sh

What It Checks

Check	What It Verifies
1. Hardcoded secrets	No apiKey/password/token/secret fields in config/openclaw.json have literal values (all should use ${VAR})
2. Runtime config drift	~/.openclaw/openclaw.json matches config/openclaw.json — no sections added directly to runtime that are missing from the repo
3. Env var resolution	Every ${VAR} in the config has a matching non-placeholder value in ~/.openclaw/.env, and OpenClaw resolves it correctly
4. .env.example coverage	Every ${VAR} reference is documented in config/.env.example
5. Git tracked files	No plaintext secrets leaked into any git-tracked file (scans first 12 chars of each secret value)
6. File permissions	~/.openclaw/.env (600), ~/.config/fastmail-cli/config.json (600), ~/.config/gh/hosts.yml (600)
7. CLI-managed auth	Fastmail CLI token is authenticated and not expiring soon

Reading the Output

🦞 Lobster Secrets Audit
========================

1. Hardcoded secrets in config/openclaw.json
  ✓ No hardcoded secrets found

2. Runtime config drift
  ✓ No hardcoded secrets in runtime config

3. Env var resolution
  ✓ BLUEBUBBLES_PASSWORD — set and resolves correctly
  ✓ BRAVE_API_KEY — set and resolves correctly
  ⚠ GEMINI_API_KEY — placeholder value (not yet configured)

4. .env.example coverage
  ✓ BLUEBUBBLES_PASSWORD — documented

5. Tracked files (plaintext secret scan)
  ✓ No known secrets in tracked files

6. File permissions
  ✓ ~/.openclaw/.env — 600 (owner-only)

7. CLI-managed auth
  ✓ Fastmail CLI — authenticated (45 days left)

========================
1 warning(s), 0 errors

• Green checkmark — check passed
• Yellow warning — non-critical issue (placeholder values, missing optional files)
• Red X — critical issue that needs fixing (hardcoded secrets, missing env vars, leaked secrets)

Each failure includes a hint with the exact fix command.

Security Audit Integration

The broader openclaw-agents/lobster/scripts/security-audit.sh calls secrets-audit.sh as part of a comprehensive security check that also validates:

• Exec approval policies (deny-by-default, per-agent allowlists)
• Agent tool policies (restricted agents can’t access sensitive tools)
• Skill isolation (apple-mail only in lobster workspace)
• Travel-hub wrapper validation (ALLOWED_TOOLS check)

bash openclaw-agents/lobster/scripts/security-audit.sh

Token Rotation

Fastmail CLI

The Fastmail CLI token expires periodically. The secrets audit warns when expiry is within 7 days.

fastmail auth                              # Re-authenticate (opens browser)
fastmail auth status                       # Check expiry

Token cached at ~/.config/fastmail-cli/config.json (should be 600 permissions).

MCP Server Tokens (Travel Hub)

Travel Hub uses HTTP transport with browser-based OAuth. Token is managed by mcporter:

1. Visit https://travel-hub-mcp.shahine.com/get-token in a browser
2. Authenticate via Cloudflare Access SSO
3. Copy the new Bearer token
4. Update the Authorization header in ~/.mcporter/mcporter.json
5. Verify: mcporter list travel-hub

Gateway Token

The OPENCLAW_GATEWAY_TOKEN authenticates local connections to the gateway. To rotate:

1. Generate a new random string
2. Update OPENCLAW_GATEWAY_TOKEN in ~/.openclaw/.env
3. Restart the gateway: openclaw gateway restart
4. Update any remote clients (iOS app, Tailscale Serve consumers)

Anthropic API Key

Managed separately via OpenClaw’s auth system:

openclaw models auth setup-token --provider anthropic