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

OpenClaw supports two complementary systems for managing secrets:

1. Environment Variable Templates (${VAR})

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.

2. Secret Refs (v2026.2.15+)

For auth profiles and supported fields, OpenClaw can resolve secrets from external sources at runtime using structured keyRef/tokenRef objects instead of plaintext values.

Three provider types are supported:

Provider	Source	Example
env	Environment variables	{ "source": "env", "id": "OPENAI_API_KEY" }
file	JSON file with pointer navigation	{ "source": "file", "provider": "secrets", "id": "/auth/anthropic/apiKey" }
exec	External binary (1Password, Vault, sops)	{ "source": "exec", "provider": "op", "id": "..." }

Configure providers in openclaw.json:

"secrets": {
  "providers": {
    "secrets": {
      "source": "file",
      "path": "~/.openclaw/secrets.json",
      "mode": "json"
    }
  },
  "defaults": {
    "file": "secrets"
  }
}

Then use refs in auth-profiles.json instead of plaintext keys:

{
  "anthropic:default": {
    "type": "api_key",
    "provider": "anthropic",
    "keyRef": { "source": "file", "provider": "secrets", "id": "/auth/anthropic/apiKey" }
  }
}

In-scope fields (v1): auth-profiles.json (keyRef, tokenRef), models.providers.<p>.apiKey. Skill apiKey fields and ${VAR} template fields are not yet supported — use env vars for those.

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

With secret refs configured, the Anthropic API key lives in ~/.openclaw/secrets.json and is referenced via keyRef in each agent’s auth-profiles.json. To rotate:

1. Get a new key from console.anthropic.com/settings/keys
2. Update the value in ~/.openclaw/secrets.json at /auth/anthropic/apiKey
3. Reload secrets: openclaw secrets reload

Without secret refs, use the interactive flow:

openclaw models auth setup-token --provider anthropic

Remember to update auth for all agents — each has its own auth-profiles.json.

Secrets Audit (Built-in)

OpenClaw v2026.2.15+ includes a built-in secrets audit:

openclaw secrets audit          # Show all findings
openclaw secrets audit --check  # Exit non-zero on findings

This scans for plaintext keys in auth profiles, config files, and .env, reporting unresolved refs and shadowed values. Use the interactive wizard to migrate:

openclaw secrets configure                    # Interactive setup
openclaw secrets apply --from /tmp/plan.json  # Apply migration plan
openclaw secrets reload                       # Reload runtime secrets