Description

OpenClaw-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.

When to Use

• Auditing OpenClaw deployments for plaintext credentials
• Migrating plaintext secrets to OpenClaw secrets management
• Troubleshooting unresolved SecretRef objects
• Coordinating gateway operations during secrets integration
• Developing security policies for OpenClaw deployments

Inputs

• Optional: Path to OpenClaw configuration directory (default: ~/.openclaw)
• Optional: Agent IDs to audit (default: all agents)
• Optional: Skip gateway operations flag (for analysis-only mode)

Outputs

• Audit report: Plaintext findings categorized by risk level
• Migration plan: Step-by-step migration instructions
• Configuration templates: Updated files with secret references
• Testing checklist: Validation steps for secrets integration
• Troubleshooting guide: Common issues and solutions

Key Learnings from Implementation

1. Gateway Coordination is Critical

• Problem: Parallel gateway restarts cause connection loss (gateway closed (1012): service restart)
• Solution: Sequential execution with only one subagent authorized for gateway operations
• Pattern: Analysis → Preparation → Application → Testing (single gateway restart)

2. OpenClaw SecretRef Format Nuances

• JSON Pointer format: References use /secret-name (JSON Pointer with leading slash)
• secrets.json keys: Use "secret-name" (NO leading slash in key names)
• Correct pattern: Reference "/secret-name" → Key "secret-name" in secrets.json
• Provider reference: Must match filemain provider name in openclaw.json

3. Different File Types, Different Approaches

• openclaw.json: Gateway token, external API keys - use SecretRef objects
• auth-profiles.json: Authentication profiles - migrate to SecretRef objects
• models.json: Model provider API keys - use placeholder "secretref-managed" string (OpenClaw resolves to secrets)

4. Testing Patterns

• Gateway health: curl http://127.0.0.1:18789/health
• Secrets audit: openclaw secrets audit
• Secrets reload: openclaw secrets reload (may need OPENCLAW_GATEWAY_TOKEN env var)
• Validation: Plaintext count reduction, unresolved reference resolution

Implementation Workflow

Phase 1: Audit & Analysis

# 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)

Phase 2: Preparation

# 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"
# }

Phase 3: Agent Configuration Updates

# 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

Phase 4: Testing & Validation

# 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.

Common Issues & Solutions

Issue 1: "JSON pointer segment does not exist"

Cause: Secret reference format mismatch Solution: Ensure secrets.json has key secret-name (no slash) for reference /secret-name

Issue 2: "gateway closed (1012): service restart"

Cause: Parallel gateway operations Solution: Sequential execution, single gateway restart point

Issue 3: "unresolved SecretRef object; regenerate models.json"

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)

Issue 4: "requires interactive TTY"

Cause: openclaw secrets configure needs terminal Solution: Manual configuration or environment variable workaround

Security Considerations

Risk Levels

• High: Gateway token, external API keys (Brave, etc.)
• Medium: Authentication profiles
• Low: Model provider keys (protected in agent directories)

Acceptable Deferred Items

• models.json API keys may remain plaintext if:

- Files are in protected agent directories (~/.openclaw/agents/*/agent/) - No world-readable permissions - Documented as technical debt

Documentation Requirements

• Migration plan with timestamps
• Policy framework for ongoing management
• Regular audit schedule (weekly recommended)

Templates & Examples

secrets.json Template

{
  "gateway-token": "REPLACE",
  "brave-api-key": "REPLACE",
  "openai-api-key": "REPLACE",
  "agent-openrouter-key": "REPLACE"
}

auth-profiles.json Update Template

{
  "version": 1,
  "profiles": {
    "provider:profile": {
      "type": "api_key",
      "provider": "provider",
      "key": {
        "source": "file",
        "provider": "filemain",
        "id": "/secret-name"
      }
    }
  }
}

Success Metrics

• Plaintext findings reduced by 70%+
• Gateway operational with secret token
• External integrations working with secret keys
• Documentation complete (migration plan, policies)
• Regular audit schedule established

---

Skill Author: Based on real OpenClaw security remediation experience by jlab1201 (2026-04-11) Lessons Incorporated: Gateway coordination, OpenClaw SecretRef patterns, emergency resolution techniques