🏠 Home ← Docs Index
Open Beta 📖 Interactive Reader Raw .md llms.txt

Secrets Vault & Configuration Interpolation

GoClaw features a secure, built-in Secrets Vault and dynamic Configuration Interpolation engine. This system ensures that API keys, webhook credentials, database passwords, and other sensitive parameters are encrypted at rest and never stored in plain-text inside configuration files.

1. Secrets Vault Architecture

The Secrets Vault is designed to provide secure credentials management on local filesystems:

flowchart TD
    CLI["<b>goclaw CLI / API</b>"] --> ENG["<b>AES-256-GCM Engine</b><br/>• PBKDF2 Key Derivation (600K iterations)<br/>• Salt: random 32 bytes per vault"]
    ENG --> FILE["<b>~/.goclaw/credentials/secrets.enc</b><br/>(File permissions: 0600)"]

2. Configuration Interpolation

GoClaw supports configuration interpolation inside config.yaml. This allows you to reference environment variables, system files, or vault secrets from the fields that hold credentials.

Supported Reference Patterns

Pattern Syntax Resolution Source Example
${secret:KEY} Looks up KEY inside the encrypted Secrets Vault. api_key: "${secret:GEMINI_API_KEY}"
${env:VAR} Fetches the value of the environment variable VAR. api_key: "${env:OPENAI_API_KEY}"
${file:/path} Reads the first line of the specified file, trimming whitespace. token: "${file:/etc/secrets/token}"
${VAR} (Bare) Fallback mode: tries environment first, then queries the Secrets Vault. token: "${DISCORD_TOKEN}"

Which Fields Are Expanded

References are expanded only in fields that hold credentials. In any other field (a port, a URL, a model name, a channel ID) a ${...} reference stays literal text. The expanded fields are:

A webhook route's secret, token and agent, whether set on the Webhooks page or under webhooks: in config.yaml, may also be a ${secret:NAME} reference; it is expanded on each delivery.

Configuration Example

Below is an example of a secure config.yaml utilizing all interpolation types:

server:
  port: "8080"            # not a credential field: written as a plain value

gateway:
  bind: "loopback"
  auth:
    token: "${secret:GATEWAY_ACCESS_TOKEN}"

ai:
  provider: "gemini"
  gemini:
    api_key: "${secret:GEMINI_API_KEY}"
  openai:
    api_key: "${env:OPENAI_API_KEY}"
  anthropic:
    api_key: "${file:/run/secrets/anthropic_key}"

channels:
  discord:
    token: "${DISCORD_BOT_TOKEN}"

3. Managing Secrets via CLI

You can easily manage your vault credentials from the terminal. The CLI supports category tags and provider association to organize tokens.

Common CLI Operations

Agent Tools

The agent has four vault tools: secret_set, secret_get, secret_list and secret_delete. Each one is refused unless a human admin is the caller; a non-admin user, and SOP, cron and webhook runs, get an access-denied error. secret_list masks values as the CLI does. secret_get returns the plaintext value to the model, so it then appears in the conversation and its trace and is sent to the LLM provider. Tools that need a credential do not need it: they get it from ${secret:NAME} expansion in their configuration.

The model can also name a vault entry without seeing it: a header it writes for http_request, or for an mcp call, may hold ${secret:NAME} (or ${env:VAR}, ${file:/path}), which is expanded as the request is sent. Only an admin, or a SOP or cron run an admin set up, may do this; for anyone else, a webhook-started run included, the call is refused. A credential a regular user's requests need belongs in the integration's own configuration instead.

4. Reload behaviour

The vault file is shared with the goclaw secret CLI, which writes it from a separate process. The gateway notices:

The config watcher accepts timestamp-only changes (touch) and continues watching when an editor saves by replacing the file. Reloads run in order. If the vault changes again during a read, that newer version remains detectable on the next reload.

A vault that cannot be decrypted — re-keyed elsewhere, or caught mid-write — leaves the already-loaded credentials in place and logs a warning rather than emptying a running gateway.

5. Troubleshooting