mirror of
https://github.com/openclaw/openclaw.git
synced 2026-03-12 07:20:45 +00:00
Docs: document secrets refs runtime and migration
This commit is contained in:
joshavant
committed by
Peter Steinberger
Peter Steinberger
parent
cb119874dc
commit
c0a3801086
@@ -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.<id>.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
|
||||
|
||||
@@ -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 <name>] <command>
|
||||
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 <backup-id>` — restore from a migration backup.
|
||||
|
||||
## Plugins
|
||||
|
||||
Manage extensions and their config:
|
||||
@@ -326,6 +336,7 @@ Options:
|
||||
- `--token <token>` (non-interactive; used with `--auth-choice token`)
|
||||
- `--token-profile-id <id>` (non-interactive; default: `<provider>:manual`)
|
||||
- `--token-expires-in <duration>` (non-interactive; e.g. `365d`, `12h`)
|
||||
- `--secret-input-mode <plaintext|ref>` (default `plaintext`; use `ref` to store provider default env refs instead of plaintext keys)
|
||||
- `--anthropic-api-key <key>`
|
||||
- `--openai-api-key <key>`
|
||||
- `--mistral-api-key <key>`
|
||||
|
||||
@@ -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`).
|
||||
|
||||
@@ -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/<agentId>/agent/auth-profiles.json`
|
||||
- Runtime cache (managed automatically; don’t edit): `~/.openclaw/agents/<agentId>/agent/auth.json`
|
||||
- Auth profiles (OAuth + API keys + optional value-level refs): `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
|
||||
- Legacy compatibility file: `~/.openclaw/agents/<agentId>/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:
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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/<agentId>/agent/auth-profiles.json` | Auth profiles (OAuth + API keys) |
|
||||
| `$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth.json` | Runtime auth cache (managed automatically) |
|
||||
| `$OPENCLAW_STATE_DIR/credentials/` | Provider state (e.g. `whatsapp/<accountId>/creds.json`) |
|
||||
| `$OPENCLAW_STATE_DIR/agents/` | Per-agent state (agentDir + sessions) |
|
||||
| `$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/` | Conversation history & state (per agent) |
|
||||
| `$OPENCLAW_STATE_DIR/agents/<agentId>/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/<agentId>/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/<agentId>/agent/auth.json` | Legacy compatibility file (static `api_key` entries scrubbed) |
|
||||
| `$OPENCLAW_STATE_DIR/credentials/` | Provider state (e.g. `whatsapp/<accountId>/creds.json`) |
|
||||
| `$OPENCLAW_STATE_DIR/agents/` | Per-agent state (agentDir + sessions) |
|
||||
| `$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/` | Conversation history & state (per agent) |
|
||||
| `$OPENCLAW_STATE_DIR/agents/<agentId>/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).
|
||||
|
||||
|
||||
@@ -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/<agentId>/agent/auth-profiles.json` (API keys + OAuth).
|
||||
- More detail: [/concepts/oauth](/concepts/oauth)
|
||||
<Note>
|
||||
|
||||
@@ -134,6 +134,8 @@ Use this when debugging auth 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`
|
||||
More detail: [Security](/gateway/security#credential-storage-map).
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
<AccordionGroup>
|
||||
|
||||
@@ -139,8 +139,7 @@ What you set:
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="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.
|
||||
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/<agentId>/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.
|
||||
|
||||
<Note>
|
||||
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`)
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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).
|
||||
|
||||
Reference in New Issue
Block a user