Summary

Add support for storing and retrieving secrets from HashiCorp Vault instead of local files (~/.claude/.credentials.json, keychain, etc.).

Motivation

Current State

OpenClaw currently stores credentials in:

• Local JSON files (~/.claude/.credentials.json, ~/.qwen/oauth_creds.json)
• System keychain (macOS/Linux)
• Environment variables

Problems with Current Approach

• ❌ Secrets scattered across multiple locations
• ❌ No centralized secret rotation
• ❌ Limited audit logging
• ❌ Difficult to manage in multi-user/team environments
• ❌ No encryption at rest (files are just JSON)

Benefits of Vault Integration

• ✅ Centralized secret management - Single source of truth
• ✅ Better security - Vault's encryption and access policies
• ✅ Secret rotation - Automated credential rotation
• ✅ Audit logging - Track who accessed which secrets
• ✅ Team support - Multiple users can share secrets safely
• ✅ Already available - Many users already run Vault in their infrastructure

Proposed Implementation

Architecture

┌─────────────┐
│  OpenClaw   │
│  Gateway    │
└──────┬──────┘
       │ 1. Request credentials
       ↓
┌─────────────────────────┐
│  Credential Provider    │
│  (with Vault support)   │
└──────┬─────────┬────────┘
       │         │
       │         └─→ Fallback to local files
       ↓
┌──────────────┐
│  HashiCorp   │
│  Vault       │
│  (HTTP API)  │
└──────────────┘

Technical Details

1. New Module: src/infra/vault-client.ts

   • VaultClient class for HTTP API communication
   • Support for KV v2 secrets engine
   • Read/write/list/delete operations

2. Configuration (via env vars or moltbot.json):

   {
     "credentials": {
       "provider": "vault",  // or "local" (default)
       "vault": {
         "addr": "http://localhost:8200",
         "token": "<vault-token>",
         "namespace": "openclaw"
       }
     }
   }

3. Environment Variables:

   • VAULT_ADDR - Vault server address
   • VAULT_TOKEN - Authentication token
   • VAULT_NAMESPACE - Optional namespace

4. Secret Structure in Vault:

   openclaw/credentials/anthropic    → OAuth tokens
   openclaw/credentials/telegram     → Bot token
   openclaw/credentials/discord      → Bot token
   openclaw/config/encryption        → Master keys
   

5. Backward Compatibility:

   • Default to local file storage if Vault not configured
   • Migration tool: openclaw vault migrate to move secrets to Vault
   • Support both providers simultaneously (Vault → fallback to local)

Related Issues

• [Feature]: Secret scanning megathread #899 (secret scanning/redaction - complements this)
• [Feature]: security audit --fix: offer to extract hardcoded secrets to .env #2320 (extract hardcoded secrets to .env)
• [Feature]: Add config option to disable external CLI credential sync #2447 (credential sync configuration)
• [Security] File Permissions Not Enforced for Sensitive Files #3002 (file permissions for sensitive files)
• [Security] Support running gateway as isolated system user instead of personal user #2341 (running gateway as isolated user)

Current Status

We will implement this as an extension first (extensions/vault-integration) to:

• Validate the approach
• Get community feedback
• Avoid blocking on core approval
• Allow faster iteration

Once proven stable, we can discuss merging into core or keeping as an optional extension.

Implementation Checklist

• Create extensions/vault-integration package
• Implement VaultClient with KV v2 support
• Add credential provider interface
• Wire up to existing credential loading logic
• Add configuration schema
• Write tests (unit + integration)
• Add documentation
• Create migration guide
• Test with real Vault instance

Questions for Maintainers

1. Architecture: Do you prefer this as a core feature or extension?
2. Scope: Should we also support other secret managers (AWS Secrets Manager, Azure Key Vault)?
3. Dependencies: OK to add node-fetch or use built-in fetch?
4. Breaking changes: Any concerns with the proposed credential provider interface?

Looking forward to your feedback! 🔐

Note: This will be implemented initially as an extension in extensions/vault-integration for faster iteration and validation. We can discuss core integration after proving the concept.