Locker Vault — Secrets Management for OpenClaw Agents#

Why This Skill Exists#

Agents that handle credentials face three risks: leaking secrets in logs/files, making redundant API calls that slow down processing, and losing access when credentials rotate. This skill eliminates all three by establishing a single pattern: every credential lives in Locker's vault, is accessed through a cached client, and is referenced by ID — never by value.

The cache layer is particularly important. Without it, every time an agent needs a credential during a conversation (which can happen dozens of times in a single session), it would make a round-trip CLI call to Locker. The cache holds decrypted values in-memory for a configurable TTL, dramatically reducing latency and API load while still respecting rotation schedules.

---

Core Principles#

These aren't arbitrary rules — they protect the business and the customer:

1. Vault is the single source of truth. Credentials are created, read, updated, and deleted exclusively through Locker. No .env files, no hardcoded values, no environment variables with raw secrets.

2. References, not values. When an agent creates a config file, cron job, script, or integration, it stores vault://SECRET_KEY_NAME (the vault reference) — never the actual token/password. At runtime, the vault-client resolves the reference.

3. Cache before call. The vault-client maintains an in-memory cache with configurable TTL. Repeated reads for the same secret within the TTL window return instantly from cache — no CLI subprocess, no network call, no latency.

4. Permission boundaries are real. A read-only agent cannot create, update, or delete secrets. Period. The agent's mode is set in its configuration, and the vault-client enforces it before any CLI call is made.

5. Secrets never appear in output. When logging, responding to users, or writing files, mask credential values. Show vault://DB_PASSWORD or *****, never the actual value.

---

Permission Levels#

Read-Only ( VAULT_MODE=ro)#

For agents that consume credentials but should never manage them — SDR agents, customer-facing bots, monitoring agents.

Allowed operations:

• get(key) — Retrieve a secret value (cached)
• list() — List available secret keys (cached)
• exists(key) — Check if a secret exists

Blocked operations (will throw error):

• create(), update(), delete() — All write operations

Read-Write ( VAULT_MODE=rw)#

For agents that manage infrastructure, rotate credentials, or onboard new integrations — DevOps agents, admin agents, integration agents.

Allowed operations:

• Everything from read-only, plus:
• create(key, value) — Store a new secret
• createRandom(key) — Generate and store a random secret
• update(key, value) — Update an existing secret
• delete(key) — Remove a secret (use with caution)

---

Architecture#

text

Agent Code
    │
    ▼
┌─────────────────────────────┐
│   vault-client.js           │
│   ┌───────────────────┐     │
│   │  In-Memory Cache  │     │  TTL-based, per-key expiry
│   │  Map<key, {val,   │     │  Default: 300s (5 min)
│   │   expiry}>         │     │  Configurable per agent
│   └───────┬───────────┘     │
│           │ cache miss      │
│           ▼                 │
│   ┌───────────────────┐     │
│   │  Permission Gate  │     │  Checks VAULT_MODE before
│   │  ro / rw          │     │  allowing write operations
│   └───────┬───────────┘     │
│           │                 │
│           ▼                 │
│   ┌───────────────────┐     │
│   │  CLI Executor     │     │  Spawns: locker secret <cmd>
│   │  (child_process)  │     │  Parses stdout, handles errors
│   └───────────────────┘     │
└─────────────────────────────┘
    │
    ▼
Locker CLI → Locker Cloud API (E2E encrypted)

Cache Behavior#

The cache is designed to balance freshness with performance:

• On get(key): Check cache first. If key exists and hasn't expired, return cached value immediately (zero latency). If expired or missing, call CLI, store result with new TTL, return value.
• On create/update(key, value): Execute CLI write, then update cache with new value and fresh TTL. This means subsequent reads see the new value instantly.
• On delete(key): Execute CLI delete, then evict key from cache.
• On list(): Cached separately with its own TTL (default: 60s, shorter because the list changes more frequently).
• Cache clear: clearCache() evicts everything — useful after bulk operations or credential rotation.
• TTL override per-key: get(key, { ttl: 600 }) can override the default TTL for secrets that rarely change (like database hosts).

Why CLI Over SDK#

The Locker Node.js SDK package isn't reliably published on npm. The CLI ( locker) is stable, well-documented, works in any environment where it's installed, and OpenClaw agents have shell access. The vault-client.js wrapper provides the ergonomic API that a native SDK would, with the added benefit of the cache layer.

---

Setup#

1. Install Locker CLI on the Agent Host#

bash

# Download and install (check locker.io/secrets/download for latest)
curl -fsSL https://locker.io/secrets/install.sh | bash

# Verify installation
locker --version

2. Authenticate the CLI#

bash

# Login with access key (non-interactive, suitable for servers)
export LOCKER_ACCESS_KEY_ID="your-access-key-id"
export LOCKER_SECRET_ACCESS_KEY="your-secret-access-key"

# Verify access
locker secret list

The access key pair is created in the Locker dashboard under your project settings. Create separate access keys for read-only and read-write agents — this provides an additional security layer beyond the vault-client's permission gate.

3. Place vault-client.js in Agent Workspace#

Copy scripts/vault-client.js into the agent's workspace. The script has zero npm dependencies — it uses only Node.js built-in modules ( child_process, util).

4. Configure the Agent#

In the agent's configuration (OpenClaw config.json or SOUL.md environment block):

json

{
  "vault": {
    "mode": "ro",
    "cacheTTL": 300,
    "listCacheTTL": 60,
    "cliPath": "locker",
    "accessKeyId": "vault://LOCKER_ACCESS_KEY_ID",
    "secretAccessKey": "vault://LOCKER_SECRET_ACCESS_KEY"
  }
}

For the bootstrap case (the vault client needs credentials to access the vault), the access key pair is the ONE exception where environment variables are acceptable — set LOCKER_ACCESS_KEY_ID and LOCKER_SECRET_ACCESS_KEY as env vars on the host. Everything else goes through the vault.

---

Usage Patterns#

Reading a Secret (Any Agent)#

javascript

const vault = require('./vault-client');

// Initialize (once per session)
await vault.init({ mode: 'ro', cacheTTL: 300 });

// Get a secret — returns from cache if available
const apiKey = await vault.get('OPENAI_API_KEY');

// Check existence without retrieving value
const hasKey = await vault.exists('SLACK_WEBHOOK');

// List all available keys
const keys = await vault.list();

Creating/Updating Secrets (Read-Write Agents Only)#

javascript

await vault.init({ mode: 'rw', cacheTTL: 300 });

// Store a new credential
await vault.create('NEW_API_KEY', 'sk-abc123...');

// Generate a random secret (great for tokens, passwords)
await vault.createRandom('SESSION_SECRET');

// Update existing
await vault.update('DB_PASSWORD', 'new-password-here');

// Delete (requires rw mode)
await vault.delete('OLD_TOKEN');

Vault References in Configs#

When an agent creates a config file, cron job, or integration config, it must use vault references:

javascript

// CORRECT — Store vault reference, resolve at runtime
const cronConfig = {
  schedule: '0 */6 * * *',
  task: 'sync_crm',
  credentials: {
    crm_token: 'vault://RD_CRM_API_TOKEN',
    webhook_url: 'vault://SLACK_WEBHOOK_SALES'
  }
};

// WRONG — Never store actual values
const cronConfig = {
  credentials: {
    crm_token: 'Bearer eyJhbGci...',  // ← NEVER DO THIS
  }
};

Resolving Vault References at Runtime#

javascript

const { resolveVaultRefs } = require('./vault-client');

// Takes any object and resolves all vault:// references
const config = await resolveVaultRefs({
  apiUrl: 'https://api.example.com',         // Not a ref, passed through
  token: 'vault://EXAMPLE_API_TOKEN',         // Resolved from vault
  dbPassword: 'vault://DB_PASSWORD_PROD',     // Resolved from vault
});
// config.token now contains the actual value, config.apiUrl unchanged

Cache Management#

javascript

// Force refresh a specific key (bypasses cache)
const fresh = await vault.get('API_KEY', { skipCache: true });

// Clear entire cache (after bulk rotation)
vault.clearCache();

// Set per-key TTL (database host rarely changes = longer cache)
const dbHost = await vault.get('DB_HOST', { ttl: 3600 }); // 1 hour

// Get cache stats (for debugging/monitoring)
const stats = vault.cacheStats();
// { size: 12, hits: 847, misses: 23, hitRate: '97.4%' }

---

Integration with OpenClaw#

In SOUL.md / AGENTS.md#

Add to the agent's bootstrap instructions:

markdown

## Credentials Policy

All credentials are managed through Locker Vault. Follow these rules without exception:

1. Use `vault-client.js` for ALL secret access
2. Never write credentials to files, logs, or chat responses
3. Store vault references (`vault://KEY_NAME`) in configs, never raw values
4. Cache is automatic — don't worry about repeated reads being slow
5. If you need a new credential stored, and you're read-only, ask the operator

In OpenClaw Agent Config#

json5

{
  agents: [{
    id: "sdr-datatem",
    workspace: "/opt/agents/sdr-datatem",
    tools: {
      allow: ["read_file", "exec"],  // exec needed for CLI calls
      deny: ["write", "edit", "browser", "gateway"]
    },
    env: {
      VAULT_MODE: "ro",
      VAULT_CACHE_TTL: "300",
      LOCKER_ACCESS_KEY_ID: "ak_xxxx",      // Bootstrap exception
      LOCKER_SECRET_ACCESS_KEY: "sk_xxxx"    // Bootstrap exception
    }
  }]
}

In Cron Jobs / Scheduled Tasks#

Agents creating scheduled tasks MUST use this pattern:

javascript

// The scheduled script reads from vault at execution time
const taskScript = `
const vault = require('./vault-client');

async function run() {
  await vault.init({ mode: 'ro' });
  const token = await vault.get('CRM_API_TOKEN');
  // Use token for the actual task...
  await syncCRM(token);
}

run().catch(console.error);
`;

// Save the script — note: no credentials in the file
fs.writeFileSync('/opt/tasks/sync-crm.js', taskScript);

---

Error Handling#

The vault-client provides clear error messages:

ErrorCauseActionVAULT_PERMISSION_DENIEDWrite operation in ro modeCheck agent's VAULT_MODE settingVAULT_KEY_NOT_FOUNDSecret doesn't exist in vaultVerify key name, check list()``VAULT_CLI_NOT_FOUND``locker binary not in PATHInstall Locker CLI on hostVAULT_AUTH_FAILEDInvalid or expired access keysRotate access key pair in dashboardVAULT_TIMEOUTCLI call took > 10sCheck network, Locker API statusVAULT_PARSE_ERRORUnexpected CLI outputCheck CLI version compatibility

All errors are non-fatal by default — the vault-client returns null on failure and logs the error. For critical secrets, use strict mode:

javascript

// Throws on error instead of returning null
const dbPass = await vault.get('DB_PASSWORD', { strict: true });

---

Security Checklist#

Before deploying an agent with vault access, verify:

• Agent's VAULT_MODE matches its actual needs (ro for most agents)
• Locker access key has minimum required permissions
• vault-client.js is in the workspace but not editable by end-users
• Agent's tool deny-list blocks write and edit (for ro agents)
• No credentials appear in SOUL.md, AGENTS.md, or any workspace file
• Cron jobs and tasks use vault references, not raw values
• Logs are configured to redact secret values
• Cache TTL is appropriate for the credential rotation schedule

---

Anti-Patterns#

Never Store Credentials Locally#

javascript

// ❌ WRONG: Writing to .env
fs.writeFileSync('.env', `API_KEY=${apiKey}`);

// ❌ WRONG: Hardcoding in config
const config = { token: 'sk-live-abc123' };

// ❌ WRONG: Logging the value
console.log(`Using API key: ${apiKey}`);

// ✅ CORRECT: Use vault reference
const config = { token: 'vault://API_KEY' };

// ✅ CORRECT: Log the reference
console.log('Using API key: vault://API_KEY');

Never Cache to Disk#

javascript

// ❌ WRONG: Persisting cache to file
fs.writeFileSync('cache.json', JSON.stringify(cache));

// ✅ CORRECT: Cache lives only in memory, dies with process
// (vault-client.js handles this automatically)

Never Expose in Responses#

javascript

// ❌ WRONG: Including in chat/API response
return `Your API key is ${apiKey}`;

// ✅ CORRECT: Confirm without revealing
return 'API key configured successfully (vault://API_KEY)';

---

File Reference#

FilePurposeWhen to Readscripts/vault-client.jsNode.js wrapper with cache, permission gate, CLI executorCopy to agent workspace during setupreferences/cli-reference.mdComplete Locker CLI command referenceWhen you need exact CLI syntaxreferences/vault-patterns.mdCommon patterns for different use casesWhen implementing a new integration

---

Quick Decision Tree#

text

Need a credential?
├─ Already in vault? → vault.get('KEY_NAME')
│   ├─ In cache? → Returns instantly (0ms)
│   └─ Not in cache? → CLI call (~200ms), caches result
├─ Not in vault yet?
│   ├─ Agent is rw? → vault.create('KEY_NAME', value)
│   └─ Agent is ro? → Ask operator to add it
└─ Creating a config/cron/task?
    └─ Always store 'vault://KEY_NAME', never the value