Docs: document secrets refs runtime and migration

2026-04-19 08:48:37 +00:00 · 2026-02-24 16:26:51 -06:00
parent cb119874dc
commit c0a3801086
19 changed files with 187 additions and 22 deletions
--- a/docs/gateway/authentication.md
+++ b/docs/gateway/authentication.md
@@ -14,6 +14,7 @@ use the long‑lived token created by `claude setup-token`.

 See [/concepts/oauth](/concepts/oauth) for the full OAuth flow and storage
 layout.
+For SecretRef-based auth (env/sops-backed refs), see [Secrets Management](/gateway/secrets).

 ## Recommended Anthropic setup (API key)

@@ -85,6 +86,11 @@ openclaw models auth paste-token --provider anthropic
 openclaw models auth paste-token --provider openrouter
 ```

+Auth profile refs are also supported for static credentials:
+
+- `api_key` credentials can use `keyRef: { source, id }`
+- `token` credentials can use `tokenRef: { source, id }`
+
 Automation-friendly check (exit `1` when expired/missing, `2` when expiring):

 ```bash
--- a/docs/gateway/configuration-reference.md
+++ b/docs/gateway/configuration-reference.md
@@ -321,6 +321,7 @@ WhatsApp runs through the gateway's web channel (Baileys Web). It starts automat
 ```

 - Service account JSON: inline (`serviceAccount`) or file-based (`serviceAccountFile`).
+- Service account SecretRef is also supported (`serviceAccountRef`).
 - Env fallbacks: `GOOGLE_CHAT_SERVICE_ACCOUNT` or `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`.
 - Use `spaces/<spaceId>` or `users/<userId>` for delivery targets.
 - `channels.googlechat.dangerouslyAllowNameMatching` re-enables mutable email principal matching (break-glass compatibility mode).
@@ -1986,7 +1987,7 @@ See [Local Models](/gateway/local-models). TL;DR: run MiniMax M2.1 via LM Studio
    },
    entries: {
      "nano-banana-pro": {
-        apiKey: "GEMINI_KEY_HERE",
+        apiKey: { source: "env", id: "GEMINI_API_KEY" }, // or plaintext string
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
@@ -1998,7 +1999,7 @@ See [Local Models](/gateway/local-models). TL;DR: run MiniMax M2.1 via LM Studio

 - `allowBundled`: optional allowlist for bundled skills only (managed/workspace skills unaffected).
 - `entries.<skillKey>.enabled: false` disables a skill even if bundled/installed.
- `entries.<skillKey>.apiKey`: convenience for skills declaring a primary env var.
+- `entries.<skillKey>.apiKey`: convenience for skills declaring a primary env var (plaintext string or SecretRef object).

 ---

@@ -2384,6 +2385,57 @@ Reference env vars in any config string with `${VAR_NAME}`:

 ---

+## Secrets
+
+Secret refs are additive: plaintext values still work.
+
+### `SecretRef`
+
+Use one object shape:
+
+```json5
+{ source: "env" | "file", id: "..." }
+```
+
+Validation:
+
+- `source: "env"` id pattern: `^[A-Z][A-Z0-9_]{0,127}$`
+- `source: "file"` id: absolute JSON pointer (for example `"/providers/openai/apiKey"`)
+
+### Supported fields in config
+
+- `models.providers.<provider>.apiKey`
+- `skills.entries.<skillKey>.apiKey`
+- `channels.googlechat.serviceAccount`
+- `channels.googlechat.serviceAccountRef`
+- `channels.googlechat.accounts.<accountId>.serviceAccount`
+- `channels.googlechat.accounts.<accountId>.serviceAccountRef`
+
+### Secret sources config
+
+```json5
+{
+  secrets: {
+    sources: {
+      env: { type: "env" }, // optional
+      file: {
+        type: "sops",
+        path: "~/.openclaw/secrets.enc.json",
+        timeoutMs: 5000,
+      },
+    },
+  },
+}
+```
+
+Notes:
+
+- `file` source requires `sops` in `PATH` (`sops >= 3.9.0`).
+- `timeoutMs` defaults to `5000`.
+- File payload must decrypt to a JSON object; `id` is resolved via JSON pointer.
+
+---
+
 ## Auth storage

 ```json5
@@ -2401,8 +2453,11 @@ Reference env vars in any config string with `${VAR_NAME}`:
 ```

 - Per-agent auth profiles stored at `<agentDir>/auth-profiles.json`.
+- Auth profiles support value-level refs (`keyRef` for `api_key`, `tokenRef` for `token`).
+- Static runtime credentials come from in-memory resolved snapshots; legacy static `auth.json` entries are scrubbed when discovered.
 - Legacy OAuth imports from `~/.openclaw/credentials/oauth.json`.
 - See [OAuth](/concepts/oauth).
+- Secrets runtime behavior and migration tooling: [Secrets Management](/gateway/secrets).

 ---

--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@@ -492,6 +492,34 @@ Rules:

 </Accordion>

+<Accordion title="Secret refs (env and encrypted file)">
+  For fields that support SecretRef objects, you can use:
+
+```json5
+{
+  models: {
+    providers: {
+      openai: { apiKey: { source: "env", id: "OPENAI_API_KEY" } },
+    },
+  },
+  skills: {
+    entries: {
+      "nano-banana-pro": {
+        apiKey: { source: "file", id: "/skills/entries/nano-banana-pro/apiKey" },
+      },
+    },
+  },
+  channels: {
+    googlechat: {
+      serviceAccountRef: { source: "file", id: "/channels/googlechat/serviceAccount" },
+    },
+  },
+}
+```
+
+SecretRef details (including `secrets.sources.file` for `sops`) are in [Secrets Management](/gateway/secrets).
+</Accordion>
+
 See [Environment](/help/environment) for full precedence and sources.

 ## Full reference
--- a/docs/gateway/index.md
+++ b/docs/gateway/index.md
@@ -16,6 +16,9 @@ Use this page for day-1 startup and day-2 operations of the Gateway service.
  <Card title="Configuration" icon="sliders" href="/gateway/configuration">
    Task-oriented setup guide + full configuration reference.
  </Card>
+  <Card title="Secrets management" icon="key-round" href="/gateway/secrets">
+    SecretRef contract, runtime snapshot behavior, and migrate/reload operations.
+  </Card>
 </CardGroup>

 ## 5-minute local startup
@@ -94,6 +97,7 @@ openclaw gateway status --json
 openclaw gateway install
 openclaw gateway restart
 openclaw gateway stop
+openclaw secrets reload
 openclaw logs --follow
 openclaw doctor
 ```
--- a/docs/gateway/security/index.md
+++ b/docs/gateway/security/index.md
@@ -206,6 +206,8 @@ Use this when auditing access or deciding what to back up:
  - `~/.openclaw/credentials/<channel>-allowFrom.json` (default account)
  - `~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json` (non-default accounts)
 - **Model auth profiles**: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
+- **Encrypted secrets payload (optional)**: `~/.openclaw/secrets.enc.json`
+- **Secrets migration backups (optional)**: `~/.openclaw/backups/secrets-migrate/<backupId>/`
 - **Legacy OAuth import**: `~/.openclaw/credentials/oauth.json`

 ## Security Audit Checklist
@@ -760,7 +762,10 @@ Assume anything under `~/.openclaw/` (or `$OPENCLAW_STATE_DIR/`) may contain sec

 - `openclaw.json`: config may include tokens (gateway, remote gateway), provider settings, and allowlists.
 - `credentials/**`: channel credentials (example: WhatsApp creds), pairing allowlists, legacy OAuth imports.
- `agents/<agentId>/agent/auth-profiles.json`: API keys + OAuth tokens (imported from legacy `credentials/oauth.json`).
+- `agents/<agentId>/agent/auth-profiles.json`: API keys, token profiles, OAuth tokens, and optional `keyRef`/`tokenRef`.
+- `secrets.enc.json` (optional): encrypted file-backed secret payload used by SecretRefs (`secrets.sources.file`).
+- `backups/secrets-migrate/**` (optional): migration rollback backups + manifests.
+- `agents/<agentId>/agent/auth.json`: legacy compatibility file. Static `api_key` entries are scrubbed when discovered.
 - `agents/<agentId>/sessions/**`: session transcripts (`*.jsonl`) + routing metadata (`sessions.json`) that can contain private messages and tool output.
 - `extensions/**`: installed plugins (plus their `node_modules/`).
 - `sandboxes/**`: tool sandbox workspaces; can accumulate copies of files you read/write inside the sandbox.
@@ -1059,7 +1064,7 @@ If your AI does something bad:

 1. Rotate Gateway auth (`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`) and restart.
 2. Rotate remote client secrets (`gateway.remote.token` / `.password`) on any machine that can call the Gateway.
-3. Rotate provider/API credentials (WhatsApp creds, Slack/Discord tokens, model/API keys in `auth-profiles.json`).
+3. Rotate provider/API credentials (WhatsApp creds, Slack/Discord tokens, model/API keys in `auth-profiles.json`, and encrypted secrets payload values when used).

 ### Audit