ewilliams28/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-08-27 21:07:01 -06:00
Code Issues Packages Projects Releases Wiki Activity
Files
clawsweeper/github-profile-rate-limit-fix
openclaw/docs/reference/secretref-credential-surface.md
T
Peter Steinberger 1fc29beba2 refactor(state): fold singleton tables into config_machine_state at schema v12 (#129876) 
* refactor(state): fold singleton tables into config_machine_state at schema v11

Eight singleton tables (skill_curator_state, update_check_state,
clawhub_promotions_feed_state, model_catalog_remote, voicewake_triggers,
voicewake_routing_config, voicewake_routing_routes,
onboarding_recommendations) were each one logical JSON value behind a
fixed key; their bespoke schemas, lazy ensures, and per-table accessors
collapse onto the shared config_machine_state KV under namespaced keys.
cron_store_epochs retires outright: it was born write-only in #114388
and no reader ever existed in any language. Durable values (update
check state, voicewake triggers and routing, per-workspace onboarding
answers) migrate insert-if-absent during the v10->v11 migration; cache
class contents rebuild on next use. Deferred with named reasons:
exec_approvals_config (macOS direct-SQL contract), installed_plugin_index
(same-tx lease fence), node_host_config and web_push_vapid_keys
(secret-table git-backup redaction).

# Conflicts:
#	src/skills/workshop/collection-review-state.ts
#	src/skills/workshop/collection-review.gateway-admission.test.ts

* test: register v11 guard carve-outs and suppression pin

The v11 migration module joins the raw-SQLite allowlist (migrations are
the named guardrail exception), the lint-suppression allowlist records
the second type-parameter suppression in config-machine-state, and the
identity module keeps only externally consumed exports.

* test: surface CLI stderr when migration-diagnostic assertion fails

* test: expect migration diagnostics on stderr for models plain commands

The #129037 pending-migration cases asserted that aliases/fallbacks
lists never open the state database, but config-health observation
(observeConfigSnapshot -> readConfigHealthStateFromStore) full-opens it
on any config read whose file exists — reproduced identically on clean
main with a main-built dist. The protected contract is exact stdout;
the diagnostic legitimately lands on stderr for every case.

* test: drop unused defaults import from CLI stdout e2e

* test: split session path derivation out of oversized session-files suite

#130016 pushed session-files.test.ts to 1008 lines, over the 1000-line
lint cap and red for every PR's check-lint. The sessionPathForFile
describe moves to a self-contained sibling following the existing
session-files.*.test.ts split pattern; no assertions change.

* refactor(state): fold four more singleton tables into schema v12

tui_last_sessions (cache-class, regenerates on next session switch),
sidebar_sections (persistent section order, migrated as one JSON array),
node_host_config, and web_push_vapid_keys join the v12 fold-in, taking
the retirement to thirteen tables at the same version. The two secret
singletons were blocked on table-granular git-backup redaction; backups
now exclude config_machine_state rows by secret key prefix (nodeHost.*,
webPush.vapidKeys) with a fail-closed row filter and regression proof,
so STATE_SECRET_TABLE_NAMES sheds both tables. The sidebar fold also
retires its lazy-ensure WeakSet and inline DDL; sidebar edits stay
inside the existing session-group write transaction via direct Kysely.

* fix(node-host): omit absent Cloudflare Access config like the column reader

The KV rewrite returned gateway.cloudflareAccess as an own undefined
property where the retired column reader omitted the key; toStrictEqual
consumers (state-migrations doctor-repair test) caught the shape drift.
Mirror the column reader's conditional spread at both construction
sites.

* fix(backup): disclose redacted machine-state prefixes after restore

The prefix-granular secret redaction recorded omitted key prefixes in
the backup manifest but the restore result exposed only excludedTables,
so a redacted restore looked complete while nodeHost.* and
webPush.vapidKeys configuration were intentionally absent. The restore
result and CLI output now disclose the omitted prefixes (JSON mode
carries them via the result shape), with restore-side regression
coverage.

* fix(tui): compare-and-delete retired session pointers

Doctor cleanup read matching pointer keys then deleted them
unconditionally, so a replacement pointer written between the scan and
the delete was erased. The delete now re-checks the stored value inside
the write transaction and only removes pointers that still name a
retired session; a live replacement survives (regression covered).
Also corrects the stale schema-version line in database-first.md.
2026-08-26 13:32:19 -07:00

9.5 KiB
Raw Permalink Blame History

summary, read_when, title
summary read_when title
Canonical supported vs unsupported SecretRef credential surface
Verifying SecretRef credential coverage
Auditing whether a credential is eligible for `secrets configure` or `secrets apply`
Verifying why a credential is outside the supported surface
SecretRef credential surface

This page defines the canonical SecretRef credential surface: which credential fields accept a SecretRef (env/file/exec/store-backed reference) instead of a raw secret value.

Scope:

  • In scope: strictly user-supplied credentials that OpenClaw does not mint or rotate.
  • Out of scope: runtime-minted or rotating credentials, OAuth refresh material, and session-like artifacts.

The lists below are generated from the source target registry and checked against docs/reference/secretref-user-supplied-credentials-matrix.json in CI; do not hand-edit entries.

Supported credentials

openclaw.json targets (secrets configure + secrets apply + secrets audit)

  • models.providers.*.apiKey
  • models.providers.*.headers.*
  • models.providers.*.request.auth.token
  • models.providers.*.request.auth.value
  • models.providers.*.request.headers.*
  • models.providers.*.request.proxy.tls.ca
  • models.providers.*.request.proxy.tls.cert
  • models.providers.*.request.proxy.tls.key
  • models.providers.*.request.proxy.tls.passphrase
  • models.providers.*.request.tls.ca
  • models.providers.*.request.tls.cert
  • models.providers.*.request.tls.key
  • models.providers.*.request.tls.passphrase
  • skills.entries.*.apiKey
  • memory.search.remote.apiKey
  • agents.entries.*.tts.providers.*.apiKey
  • agents.entries.*.memory.search.remote.apiKey
  • talk.providers.*.apiKey
  • talk.realtime.providers.*.apiKey
  • tts.providers.*.apiKey
  • plugins.entries.acpx.config.mcpServers.*.env.*
  • plugins.entries.brave.config.webSearch.apiKey
  • plugins.entries.codex.config.appServer.authToken
  • plugins.entries.codex.config.appServer.headers.*
  • plugins.entries.exa.config.webSearch.apiKey
  • plugins.entries.firecrawl.config.webFetch.apiKey
  • plugins.entries.google-meet.config.realtime.providers.*.apiKey
  • plugins.entries.google.config.webSearch.apiKey
  • plugins.entries.google.config.webSearch.headers.*
  • plugins.entries.imap.config.accounts.*.password
  • plugins.entries.xai.config.webSearch.apiKey
  • plugins.entries.moonshot.config.webSearch.apiKey
  • plugins.entries.perplexity.config.webSearch.apiKey
  • plugins.entries.firecrawl.config.webSearch.apiKey
  • plugins.entries.minimax.config.webSearch.apiKey
  • plugins.entries.tavily.config.webSearch.apiKey
  • plugins.entries.parallel.config.webSearch.apiKey
  • plugins.entries.voice-call.config.realtime.providers.*.apiKey
  • plugins.entries.voice-call.config.streaming.providers.*.apiKey
  • plugins.entries.voice-call.config.tts.providers.*.apiKey
  • plugins.entries.voice-call.config.twilio.authToken
  • plugins.entries.webhooks.config.routes.*.secret
  • gateway.auth.password
  • gateway.auth.token
  • gateway.remote.token
  • gateway.remote.password
  • cron.webhookToken
  • channels.telegram.botToken
  • channels.telegram.webhookSecret
  • channels.telegram.accounts.*.botToken
  • channels.telegram.accounts.*.webhookSecret
  • channels.slack.botToken
  • channels.slack.appToken
  • channels.slack.relay.authToken
  • channels.slack.userToken
  • channels.slack.signingSecret
  • channels.slack.accounts.*.botToken
  • channels.slack.accounts.*.appToken
  • channels.slack.accounts.*.relay.authToken
  • channels.slack.accounts.*.userToken
  • channels.slack.accounts.*.signingSecret
  • channels.sms.authToken
  • channels.sms.accounts.*.authToken
  • channels.buzz.authTag
  • channels.buzz.privateKey
  • channels.clickclack.token
  • channels.clickclack.accounts.*.token
  • channels.discord.token
  • channels.discord.pluralkit.token
  • channels.discord.voice.realtime.providers.*.apiKey
  • channels.discord.voice.tts.providers.*.apiKey
  • channels.discord.accounts.*.token
  • channels.discord.accounts.*.pluralkit.token
  • channels.discord.accounts.*.voice.realtime.providers.*.apiKey
  • channels.discord.accounts.*.voice.tts.providers.*.apiKey
  • channels.irc.password
  • channels.irc.nickserv.password
  • channels.irc.accounts.*.password
  • channels.irc.accounts.*.nickserv.password
  • channels.feishu.appSecret
  • channels.feishu.encryptKey
  • channels.feishu.verificationToken
  • channels.feishu.accounts.*.appSecret
  • channels.feishu.accounts.*.encryptKey
  • channels.feishu.accounts.*.verificationToken
  • channels.qqbot.clientSecret
  • channels.qqbot.accounts.*.clientSecret
  • channels.msteams.appPassword
  • channels.mattermost.botToken
  • channels.mattermost.accounts.*.botToken
  • channels.matrix.accessToken
  • channels.matrix.password
  • channels.matrix.accounts.*.accessToken
  • channels.matrix.accounts.*.password
  • channels.nextcloud-talk.botSecret
  • channels.nextcloud-talk.apiPassword
  • channels.nextcloud-talk.accounts.*.botSecret
  • channels.nextcloud-talk.accounts.*.apiPassword
  • channels.nostr.privateKey
  • channels.zalo.botToken
  • channels.zalo.webhookSecret
  • channels.zalo.accounts.*.botToken
  • channels.zalo.accounts.*.webhookSecret
  • channels.googlechat.serviceAccount
  • channels.googlechat.accounts.*.serviceAccount

auth-profiles.json targets (secrets configure + secrets apply + secrets audit)

  • profiles.*.keyRef (type: "api_key"; unsupported when auth.profiles.<id>.mode = "oauth")
  • profiles.*.tokenRef (type: "token"; unsupported when auth.profiles.<id>.mode = "oauth")

Node-host connection targets

  • gateway.cloudflareAccess.clientId
  • gateway.cloudflareAccess.clientSecret

These fields live in the node host's canonical nodeHost.config SQLite machine-state value, not openclaw.json. They accept the same SecretInput forms and resolve through the configured SecretRef providers when the node starts. The conventional CF_ACCESS_CLIENT_ID / CF_ACCESS_CLIENT_SECRET fallback persists env refs for these fields automatically. They are not targets for secrets configure or secrets apply.

Notes:

  • Store refs use names matching ^[A-Z][A-Z0-9_]{0,127}$ and resolve only from the Gateway-wide team scope in this release. A typical ref is {"source":"store","provider":"default","id":"OPENAI_API_KEY"}.
  • Auth-profile plan targets require agentId; plan entries target profiles.*.key / profiles.*.token and write sibling refs (keyRef / tokenRef). Auth-profile refs are included in runtime resolution and audit coverage.
  • In openclaw.json, SecretRefs must use structured objects such as {"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}. Legacy secretref-env:<ENV_VAR> marker strings are rejected on SecretRef credential paths; run openclaw doctor --fix to migrate valid markers.
  • OAuth policy guard: auth.profiles.<id>.mode = "oauth" cannot be combined with SecretRef inputs for that profile. Startup/reload and auth-profile resolution fail fast when this policy is violated.
  • For SecretRef-managed model providers, generated agents/*/agent/models.json entries persist non-secret markers (not resolved secret values) for apiKey/header surfaces. Marker persistence is source-authoritative: OpenClaw writes markers from the active source config snapshot (pre-resolution), not from resolved runtime secret values.
  • Cold Gateway startup can isolate retryable resolution failures for mapped, non-Gateway owners. Current mapped classes include model providers and skills, media/TTS/cron providers, eligible auth profiles, per-agent memory, sandbox SSH, channel accounts, and manifest-declared plugin routes. Startup keeps each failed owner's explicit refs in the runtime snapshot, reports the owner through status and doctor, and rejects requests for that owner without trying lower-precedence credentials. Reload and config-write preflight use the same owner-aware policy: healthy owners refresh; an eligible failed owner stays stale only when its ref identities, provider definitions, and complete non-secret owner contract are unchanged; a new or changed failure becomes cold. Gateway ingress auth, structurally invalid refs or values, fail-closed owners, and currently unmapped owners remain strict.
  • For web search: in explicit provider mode (tools.web.search.provider set), only the selected provider key is active. In auto mode (tools.web.search.provider unset), only the first provider key that resolves by precedence is active, and non-selected provider refs are treated as inactive until selected. Provider credentials use plugins.entries.<plugin>.config.webSearch.*.
  • Slack identity: "user" uses channels.slack.userToken with channels.slack.appToken for Socket Mode or channels.slack.signingSecret for HTTP mode. The same pairing applies under channels.slack.accounts.*; no bot token is required for this identity.

Unsupported credentials

These credentials are minted, rotated, session-bearing, or OAuth-durable classes that do not fit read-only external SecretRef resolution:

  • hooks.token
  • hooks.gmail.pushToken
  • hooks.mappings[].sessionKey
  • auth-profiles.oauth.*
  • channels.discord.threadBindings.webhookToken
  • channels.discord.accounts.*.threadBindings.webhookToken
  • channels.whatsapp.creds.json
  • channels.whatsapp.accounts.*.creds.json

Related

Reference in New Issue View Git Blame Copy Permalink