Install
openclaw skills install @jlab1201/openclaw-secrets-hygieneManage and audit OpenClaw secrets by coordinating gateway restarts, converting plaintext credentials to SecretRef format, and validating configuration accuracy.
openclaw skills install @jlab1201/openclaw-secrets-hygieneOpenClaw-specific secrets management and credential hygiene based on real implementation experience. Handles OpenClaw's unique patterns: gateway coordination, SecretRef format nuances, auth-profiles.json vs models.json differences, and sequential execution to avoid gateway conflicts.
~/.openclaw)gateway closed (1012): service restart)/secret-name (JSON Pointer with leading slash)"secret-name" (NO leading slash in key names)"/secret-name" → Key "secret-name" in secrets.jsonfilemain provider name in openclaw.json"secretref-managed" string (OpenClaw resolves to secrets)curl http://127.0.0.1:18789/healthopenclaw secrets auditopenclaw secrets reload (may need OPENCLAW_GATEWAY_TOKEN env var)# 1. Initial audit
openclaw secrets audit
# 2. Categorize findings
# - openclaw.json: Gateway token, external API keys
# - auth-profiles.json: Authentication profiles
# - models.json: Model provider API keys
# 3. Risk assessment
# High: Gateway token, external API keys
# Medium: Authentication profiles
# Low: Model provider keys (agent-directory protected)
# 1. Create centralized secrets file
mkdir -p ~/.openclaw
cat > ~/.openclaw/secrets.json << 'EOF'
{
"gateway-token": "REPLACE_WITH_TOKEN",
"brave-api-key": "REPLACE_WITH_KEY",
"openai-api-key": "REPLACE_WITH_KEY",
"agent-openrouter-key": "REPLACE_WITH_KEY"
}
EOF
chmod 600 ~/.openclaw/secrets.json
# 2. Update openclaw.json with secret references
# Change plaintext values to:
# {
# "source": "file",
# "provider": "filemain",
# "id": "/secret-name"
# }
# 1. Update auth-profiles.json files
# Change "key": "plaintext" to:
# "key": {
# "source": "file",
# "provider": "filemain",
# "id": "/secret-name"
# }
# 2. Handle models.json API keys
# Use placeholder string (OpenClaw will resolve from secrets):
# "apiKey": "secretref-managed"
# NOT SecretRef objects (causes unresolved references)
# OpenClaw replaces placeholder with actual secret at runtime
# 1. Set gateway token for CLI operations
export OPENCLAW_GATEWAY_TOKEN="your-token"
# 2. Reload secrets
openclaw secrets reload
# 3. Verify audit improvement
openclaw secrets audit
# 4. Test gateway functionality
curl http://127.0.0.1:18789/health
# 5. Test external integrations (if applicable)
# Brave search, model API calls, etc.
Cause: Secret reference format mismatch
Solution: Ensure secrets.json has key secret-name (no slash) for reference /secret-name
Cause: Parallel gateway operations Solution: Sequential execution, single gateway restart point
Cause: models.json contains SecretRef objects instead of placeholder strings
Solution: Replace SecretRef objects with "secretref-managed" placeholder string
Emergency fix: Use Python/script to convert {"source": "file", ...} → "secretref-managed"
import json
with open('models.json', 'r') as f:
data = json.load(f)
if 'providers' in data:
for provider in data['providers']:
if 'apiKey' in data['providers'][provider]:
if isinstance(data['providers'][provider]['apiKey'], dict):
data['providers'][provider]['apiKey'] = 'secretref-managed'
with open('models.json', 'w') as f:
json.dump(data, f, indent=2)
Cause: openclaw secrets configure needs terminal
Solution: Manual configuration or environment variable workaround
~/.openclaw/agents/*/agent/){
"gateway-token": "REPLACE",
"brave-api-key": "REPLACE",
"openai-api-key": "REPLACE",
"agent-openrouter-key": "REPLACE"
}
{
"version": 1,
"profiles": {
"provider:profile": {
"type": "api_key",
"provider": "provider",
"key": {
"source": "file",
"provider": "filemain",
"id": "/secret-name"
}
}
}
}
Skill Author: Based on real OpenClaw security remediation experience by jlab1201 (2026-04-11) Lessons Incorporated: Gateway coordination, OpenClaw SecretRef patterns, emergency resolution techniques