diff --git a/docs/channels/googlechat.md b/docs/channels/googlechat.md index 13729257fe7..ff3fa812a4d 100644 --- a/docs/channels/googlechat.md +++ b/docs/channels/googlechat.md @@ -166,6 +166,7 @@ Use these identifiers for delivery and allowlists: googlechat: { enabled: true, serviceAccountFile: "/path/to/service-account.json", + // or serviceAccountRef: { source: "file", id: "/channels/googlechat/serviceAccount" } audienceType: "app-url", audience: "https://gateway.example.com/googlechat", webhookPath: "/googlechat", @@ -194,12 +195,15 @@ Use these identifiers for delivery and allowlists: Notes: - Service account credentials can also be passed inline with `serviceAccount` (JSON string). +- `serviceAccountRef` is also supported (env/file SecretRef), including per-account refs under `channels.googlechat.accounts..serviceAccountRef`. - Default webhook path is `/googlechat` if `webhookPath` isn’t set. - `dangerouslyAllowNameMatching` re-enables mutable email principal matching for allowlists (break-glass compatibility mode). - Reactions are available via the `reactions` tool and `channels action` when `actions.reactions` is enabled. - `typingIndicator` supports `none`, `message` (default), and `reaction` (reaction requires user OAuth). - Attachments are downloaded through the Chat API and stored in the media pipeline (size capped by `mediaMaxMb`). +Secrets reference details: [Secrets Management](/gateway/secrets). + ## Troubleshooting ### 405 Method Not Allowed diff --git a/docs/cli/index.md b/docs/cli/index.md index a780dfd2a5e..faf16d96f50 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -52,6 +52,7 @@ This page describes the current CLI behavior. If commands change, update this do - [`plugins`](/cli/plugins) (plugin commands) - [`channels`](/cli/channels) - [`security`](/cli/security) +- [`secrets`](/cli/secrets) - [`skills`](/cli/skills) - [`daemon`](/cli/daemon) (legacy alias for gateway service commands) - [`clawbot`](/cli/clawbot) (legacy alias namespace) @@ -104,6 +105,9 @@ openclaw [--dev] [--profile ] dashboard security audit + secrets + reload + migrate reset uninstall update @@ -263,6 +267,12 @@ Note: plugins can add additional top-level commands (for example `openclaw voice - `openclaw security audit --deep` — best-effort live Gateway probe. - `openclaw security audit --fix` — tighten safe defaults and chmod state/config. +## Secrets + +- `openclaw secrets reload` — re-resolve refs and atomically swap the runtime snapshot. +- `openclaw secrets migrate` — migrate plaintext static secrets to file-backed refs (`--write` to apply; dry-run by default). +- `openclaw secrets migrate --rollback ` — restore from a migration backup. + ## Plugins Manage extensions and their config: @@ -326,6 +336,7 @@ Options: - `--token ` (non-interactive; used with `--auth-choice token`) - `--token-profile-id ` (non-interactive; default: `:manual`) - `--token-expires-in ` (non-interactive; e.g. `365d`, `12h`) +- `--secret-input-mode ` (default `plaintext`; use `ref` to store provider default env refs instead of plaintext keys) - `--anthropic-api-key ` - `--openai-api-key ` - `--mistral-api-key ` diff --git a/docs/cli/onboard.md b/docs/cli/onboard.md index 83aeaeaf3be..47f33ba72bf 100644 --- a/docs/cli/onboard.md +++ b/docs/cli/onboard.md @@ -34,11 +34,23 @@ openclaw onboard --non-interactive \ --custom-base-url "https://llm.example.com/v1" \ --custom-model-id "foo-large" \ --custom-api-key "$CUSTOM_API_KEY" \ + --secret-input-mode plaintext \ --custom-compatibility openai ``` `--custom-api-key` is optional in non-interactive mode. If omitted, onboarding checks `CUSTOM_API_KEY`. +Store provider keys as refs instead of plaintext: + +```bash +openclaw onboard --non-interactive \ + --auth-choice openai-api-key \ + --secret-input-mode ref \ + --accept-risk +``` + +With `--secret-input-mode ref`, onboarding writes provider default env refs (for example `OPENAI_API_KEY`) into auth profiles instead of plaintext key values. + Non-interactive Z.AI endpoint choices: Note: `--auth-choice zai-api-key` now auto-detects the best Z.AI endpoint for your key (prefers the general API with `zai/glm-5`). diff --git a/docs/concepts/oauth.md b/docs/concepts/oauth.md index 586406cf6b1..741867f188f 100644 --- a/docs/concepts/oauth.md +++ b/docs/concepts/oauth.md @@ -40,8 +40,9 @@ To reduce that, OpenClaw treats `auth-profiles.json` as a **token sink**: Secrets are stored **per-agent**: -- Auth profiles (OAuth + API keys): `~/.openclaw/agents//agent/auth-profiles.json` -- Runtime cache (managed automatically; don’t edit): `~/.openclaw/agents//agent/auth.json` +- Auth profiles (OAuth + API keys + optional value-level refs): `~/.openclaw/agents//agent/auth-profiles.json` +- Legacy compatibility file: `~/.openclaw/agents//agent/auth.json` + (static `api_key` entries are scrubbed when discovered) Legacy import-only file (still supported, but not the main store): @@ -49,6 +50,8 @@ Legacy import-only file (still supported, but not the main store): All of the above also respect `$OPENCLAW_STATE_DIR` (state dir override). Full reference: [/gateway/configuration](/gateway/configuration#auth-storage-oauth--api-keys) +For static secret refs and runtime snapshot activation behavior, see [Secrets Management](/gateway/secrets). + ## Anthropic setup-token (subscription auth) Run `claude setup-token` on any machine, then paste it into OpenClaw: diff --git a/docs/docs.json b/docs/docs.json index 5f6b21d7e82..bd796efd666 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1140,6 +1140,7 @@ "gateway/configuration-reference", "gateway/configuration-examples", "gateway/authentication", + "gateway/secrets", "gateway/trusted-proxy-auth", "gateway/health", "gateway/heartbeat", @@ -1236,6 +1237,7 @@ "cli/reset", "cli/sandbox", "cli/security", + "cli/secrets", "cli/sessions", "cli/setup", "cli/skills", diff --git a/docs/gateway/authentication.md b/docs/gateway/authentication.md index 8dd18f8416d..3b68633730c 100644 --- 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 diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index a715ec89ba6..9f18bf8d48b 100644 --- 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/` or `users/` 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..enabled: false` disables a skill even if bundled/installed. -- `entries..apiKey`: convenience for skills declaring a primary env var. +- `entries..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..apiKey` +- `skills.entries..apiKey` +- `channels.googlechat.serviceAccount` +- `channels.googlechat.serviceAccountRef` +- `channels.googlechat.accounts..serviceAccount` +- `channels.googlechat.accounts..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 `/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). --- diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md index ff3179d28e2..5e319cb18bd 100644 --- a/docs/gateway/configuration.md +++ b/docs/gateway/configuration.md @@ -492,6 +492,34 @@ Rules: + + 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). + + See [Environment](/help/environment) for full precedence and sources. ## Full reference diff --git a/docs/gateway/index.md b/docs/gateway/index.md index c1e06d63457..8b4ef53aecb 100644 --- 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. Task-oriented setup guide + full configuration reference. + + SecretRef contract, runtime snapshot behavior, and migrate/reload operations. + ## 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 ``` diff --git a/docs/gateway/security/index.md b/docs/gateway/security/index.md index 32a2a55329d..f335d7424ba 100644 --- 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/-allowFrom.json` (default account) - `~/.openclaw/credentials/--allowFrom.json` (non-default accounts) - **Model auth profiles**: `~/.openclaw/agents//agent/auth-profiles.json` +- **Encrypted secrets payload (optional)**: `~/.openclaw/secrets.enc.json` +- **Secrets migration backups (optional)**: `~/.openclaw/backups/secrets-migrate//` - **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//agent/auth-profiles.json`: API keys + OAuth tokens (imported from legacy `credentials/oauth.json`). +- `agents//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//agent/auth.json`: legacy compatibility file. Static `api_key` entries are scrubbed when discovered. - `agents//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 diff --git a/docs/help/environment.md b/docs/help/environment.md index 7e969c816a5..a404c9cb030 100644 --- a/docs/help/environment.md +++ b/docs/help/environment.md @@ -74,6 +74,15 @@ You can reference env vars directly in config string values using `${VAR_NAME}` See [Configuration: Env var substitution](/gateway/configuration#env-var-substitution-in-config) for full details. +## Secret refs vs `${ENV}` strings + +OpenClaw supports two env-driven patterns: + +- `${VAR}` string substitution in config values. +- SecretRef objects (`{ source: "env", id: "VAR" }`) for fields that support secrets references. + +Both resolve from process env at activation time. SecretRef details are documented in [Secrets Management](/gateway/secrets). + ## Path-related env vars | Variable | Purpose | diff --git a/docs/help/faq.md b/docs/help/faq.md index b5c5fa8f24a..3becbb62e49 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -1291,16 +1291,18 @@ Related: [Agent workspace](/concepts/agent-workspace), [Memory](/concepts/memory Everything lives under `$OPENCLAW_STATE_DIR` (default: `~/.openclaw`): -| Path | Purpose | -| --------------------------------------------------------------- | ------------------------------------------------------------ | -| `$OPENCLAW_STATE_DIR/openclaw.json` | Main config (JSON5) | -| `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Legacy OAuth import (copied into auth profiles on first use) | -| `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Auth profiles (OAuth + API keys) | -| `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Runtime auth cache (managed automatically) | -| `$OPENCLAW_STATE_DIR/credentials/` | Provider state (e.g. `whatsapp//creds.json`) | -| `$OPENCLAW_STATE_DIR/agents/` | Per-agent state (agentDir + sessions) | -| `$OPENCLAW_STATE_DIR/agents//sessions/` | Conversation history & state (per agent) | -| `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Session metadata (per agent) | +| Path | Purpose | +| --------------------------------------------------------------- | ----------------------------------------------------------------- | +| `$OPENCLAW_STATE_DIR/openclaw.json` | Main config (JSON5) | +| `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Legacy OAuth import (copied into auth profiles on first use) | +| `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Auth profiles (OAuth, API keys, and optional `keyRef`/`tokenRef`) | +| `$OPENCLAW_STATE_DIR/secrets.enc.json` | Optional encrypted file-backed secret payload (`sops`) | +| `$OPENCLAW_STATE_DIR/backups/secrets-migrate/` | Optional migration rollback backups + manifests | +| `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Legacy compatibility file (static `api_key` entries scrubbed) | +| `$OPENCLAW_STATE_DIR/credentials/` | Provider state (e.g. `whatsapp//creds.json`) | +| `$OPENCLAW_STATE_DIR/agents/` | Per-agent state (agentDir + sessions) | +| `$OPENCLAW_STATE_DIR/agents//sessions/` | Conversation history & state (per agent) | +| `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Session metadata (per agent) | Legacy single-agent path: `~/.openclaw/agent/*` (migrated by `openclaw doctor`). @@ -1338,7 +1340,7 @@ Put your **agent workspace** in a **private** git repo and back it up somewhere private (for example GitHub private). This captures memory + AGENTS/SOUL/USER files, and lets you restore the assistant's "mind" later. -Do **not** commit anything under `~/.openclaw` (credentials, sessions, tokens). +Do **not** commit anything under `~/.openclaw` (credentials, sessions, tokens, encrypted secrets payloads, or migration backups). If you need a full restore, back up both the workspace and the state directory separately (see the migration question above). diff --git a/docs/reference/wizard.md b/docs/reference/wizard.md index 1bd83a0bc28..8321f2d683b 100644 --- a/docs/reference/wizard.md +++ b/docs/reference/wizard.md @@ -34,7 +34,7 @@ For a high-level overview, see [Onboarding Wizard](/start/wizard). - **OpenAI Code (Codex) subscription (Codex CLI)**: if `~/.codex/auth.json` exists, the wizard can reuse it. - **OpenAI Code (Codex) subscription (OAuth)**: browser flow; paste the `code#state`. - Sets `agents.defaults.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`. - - **OpenAI API key**: uses `OPENAI_API_KEY` if present or prompts for a key, then saves it to `~/.openclaw/.env` so launchd can read it. + - **OpenAI API key**: uses `OPENAI_API_KEY` if present or prompts for a key, then stores it in auth profiles. - **xAI (Grok) API key**: prompts for `XAI_API_KEY` and configures xAI as a model provider. - **OpenCode Zen (multi-model proxy)**: prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`, get it at https://opencode.ai/auth). - **API key**: stores the key for you. @@ -52,6 +52,7 @@ For a high-level overview, see [Onboarding Wizard](/start/wizard). - **Skip**: no auth configured yet. - Pick a default model from detected options (or enter provider/model manually). - Wizard runs a model check and warns if the configured model is unknown or missing auth. + - API key storage mode defaults to plaintext auth-profile values. Use `--secret-input-mode ref` to store env-backed refs instead (for example `keyRef: { source: "env", id: "OPENAI_API_KEY" }`). - OAuth credentials live in `~/.openclaw/credentials/oauth.json`; auth profiles live in `~/.openclaw/agents//agent/auth-profiles.json` (API keys + OAuth). - More detail: [/concepts/oauth](/concepts/oauth) diff --git a/docs/start/setup.md b/docs/start/setup.md index 7eef5bce714..d0185c4b133 100644 --- a/docs/start/setup.md +++ b/docs/start/setup.md @@ -134,6 +134,8 @@ Use this when debugging auth or deciding what to back up: - `~/.openclaw/credentials/-allowFrom.json` (default account) - `~/.openclaw/credentials/--allowFrom.json` (non-default accounts) - **Model auth profiles**: `~/.openclaw/agents//agent/auth-profiles.json` +- **Encrypted secrets payload (optional)**: `~/.openclaw/secrets.enc.json` +- **Secrets migration backups (optional)**: `~/.openclaw/backups/secrets-migrate//` - **Legacy OAuth import**: `~/.openclaw/credentials/oauth.json` More detail: [Security](/gateway/security#credential-storage-map). diff --git a/docs/start/wizard-cli-automation.md b/docs/start/wizard-cli-automation.md index 5a8d3e9ac0e..0e4fc57f5ea 100644 --- a/docs/start/wizard-cli-automation.md +++ b/docs/start/wizard-cli-automation.md @@ -22,6 +22,7 @@ openclaw onboard --non-interactive \ --mode local \ --auth-choice apiKey \ --anthropic-api-key "$ANTHROPIC_API_KEY" \ + --secret-input-mode plaintext \ --gateway-port 18789 \ --gateway-bind loopback \ --install-daemon \ @@ -31,6 +32,18 @@ openclaw onboard --non-interactive \ Add `--json` for a machine-readable summary. +Use `--secret-input-mode ref` to store env-backed refs in auth profiles instead of plaintext values. + +Example: + +```bash +openclaw onboard --non-interactive \ + --mode local \ + --auth-choice openai-api-key \ + --secret-input-mode ref \ + --accept-risk +``` + ## Provider-specific examples diff --git a/docs/start/wizard-cli-reference.md b/docs/start/wizard-cli-reference.md index 96fd1d87afc..a02f462934b 100644 --- a/docs/start/wizard-cli-reference.md +++ b/docs/start/wizard-cli-reference.md @@ -139,8 +139,7 @@ What you set: - Uses `OPENAI_API_KEY` if present or prompts for a key, then saves it to - `~/.openclaw/.env` so launchd can read it. + Uses `OPENAI_API_KEY` if present or prompts for a key, then stores the credential in auth profiles. Sets `agents.defaults.model` to `openai/gpt-5.1-codex` when model is unset, `openai/*`, or `openai-codex/*`. @@ -202,6 +201,12 @@ Credential and profile paths: - OAuth credentials: `~/.openclaw/credentials/oauth.json` - Auth profiles (API keys + OAuth): `~/.openclaw/agents//agent/auth-profiles.json` +API key storage mode: + +- Default onboarding behavior persists API keys as plaintext values in auth profiles. +- `--secret-input-mode ref` stores env-backed refs in auth profiles instead of plaintext values (for example `keyRef: { source: "env", id: "OPENAI_API_KEY" }`). +- Existing plaintext setups continue to work unchanged. + Headless and server tip: complete OAuth on a machine with a browser, then copy `~/.openclaw/credentials/oauth.json` (or `$OPENCLAW_STATE_DIR/credentials/oauth.json`) diff --git a/docs/start/wizard.md b/docs/start/wizard.md index d653574f488..a676b3c5e2e 100644 --- a/docs/start/wizard.md +++ b/docs/start/wizard.md @@ -65,6 +65,7 @@ The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control). 1. **Model/Auth** — Anthropic API key (recommended), OpenAI, or Custom Provider (OpenAI-compatible, Anthropic-compatible, or Unknown auto-detect). Pick a default model. + For non-interactive runs, `--secret-input-mode ref` stores env-backed refs in auth profiles instead of plaintext API key values. 2. **Workspace** — Location for agent files (default `~/.openclaw/workspace`). Seeds bootstrap files. 3. **Gateway** — Port, bind address, auth mode, Tailscale exposure. 4. **Channels** — WhatsApp, Telegram, Discord, Google Chat, Mattermost, Signal, BlueBubbles, or iMessage. diff --git a/docs/tools/skills-config.md b/docs/tools/skills-config.md index d4d666ec198..0bd5362ebd3 100644 --- a/docs/tools/skills-config.md +++ b/docs/tools/skills-config.md @@ -26,7 +26,7 @@ All skills-related configuration lives under `skills` in `~/.openclaw/openclaw.j entries: { "nano-banana-pro": { enabled: true, - apiKey: "GEMINI_KEY_HERE", + apiKey: { source: "env", id: "GEMINI_API_KEY" }, // or plaintext string env: { GEMINI_API_KEY: "GEMINI_KEY_HERE", }, @@ -56,6 +56,7 @@ Per-skill fields: - `enabled`: set `false` to disable a skill even if it’s bundled/installed. - `env`: environment variables injected for the agent run (only if not already set). - `apiKey`: optional convenience for skills that declare a primary env var. + Supports plaintext string or SecretRef object (`{ source, id }`). ## Notes diff --git a/docs/tools/skills.md b/docs/tools/skills.md index 1e5fa2c5048..fd437b3649c 100644 --- a/docs/tools/skills.md +++ b/docs/tools/skills.md @@ -195,7 +195,7 @@ Bundled/managed skills can be toggled and supplied with env values: entries: { "nano-banana-pro": { enabled: true, - apiKey: "GEMINI_KEY_HERE", + apiKey: { source: "env", id: "GEMINI_API_KEY" }, // or plaintext string env: { GEMINI_API_KEY: "GEMINI_KEY_HERE", }, @@ -221,6 +221,7 @@ Rules: - `enabled: false` disables the skill even if it’s bundled/installed. - `env`: injected **only if** the variable isn’t already set in the process. - `apiKey`: convenience for skills that declare `metadata.openclaw.primaryEnv`. + Supports plaintext string or SecretRef object (`{ source, id }`). - `config`: optional bag for custom per-skill fields; custom keys must live here. - `allowBundled`: optional allowlist for **bundled** skills only. If set, only bundled skills in the list are eligible (managed/workspace skills unaffected).