RFC: Credential Provider Plugin

Full RFC (80 KB): https://gist.github.com/loveyana/a42c4bc48f71fdac772a09db02d9a802

This issue contains the summary, motivation, and design overview. The full proposal — including detailed interface definitions, code examples, migration plan, security model, appendices, and open questions — is in the linked gist above.

Summary

Introduce a new plugin capability — Credential Provider Plugin — that allows plugins to register as credential sources for the entire OpenClaw ecosystem. A Credential Provider Plugin can supply, refresh, and rotate credentials consumed by model providers, channels, skills, tools, and other plugins through a dedicated CredentialProvider abstraction that is independent of the existing SecretRef system.

Key architectural decision: SecretRef (env/file/exec) remains unchanged as the static secret injection mechanism. CredentialProvider is a new, parallel abstraction for credential acquisition, lifecycle management, and interactive authentication flows. The two systems coexist: consumers pick the right tool for the job.

Motivation

The problem today

OpenClaw's credential management is split across three independent domains, each with its own storage, resolution, and lifecycle patterns:

SecretRef (shipped in v2026.3.2, PR #26155) provides a cross-cutting credential injection mechanism with three backends (env, file, exec). It is well-suited for its original design purpose — static, resolve-once, string-value injection at startup — but it was never designed for:

• Interactive authentication flows (OAuth dance, device code, SSO)
• Token refresh and rotation (expired access tokens, rotated API keys)
• Per-session credential scoping (different users get different credentials)
• Health checks (is this credential still valid?)
• Typed credential semantics (an OAuth token is not the same as an API key)
• Cross-plugin credential sharing (one provider, many consumers)
• Plugin-native credential backends (enterprise identity services, OS keychains, and third-party secret managers as first-class plugins)

Why not extend SecretRef?

Community demand

• #55822 — "Support Keychain/Secret Store for API Keys" — explicitly proposes "Option C: Plugin-based Secret Provider"
• #7916 — "Support for encrypted API keys / secrets management" — 16+ comments, multiple community implementations
• #33541 — "SecretRef support for plugins.entries.*.config.*"
• #10659 — "Masked Secrets: Prevent Agent from Accessing Raw API Keys"
• #37303 — "Onboarding crashes when using exec secret provider"

Design goals

1. Unified credential source — one plugin can supply credentials for models, channels, skills, tools, and other plugins
2. Full lifecycle — support interactive setup, non-interactive resolve, refresh, rotation, health check, and revocation
3. Native plugin integration — Credential Provider Plugins are first-class OpenClaw plugins using the standard Plugin SDK
4. Parallel to SecretRef — SecretRef (env/file/exec) stays unchanged; CredentialProvider is an independent system
5. Incremental adoption — consumers can opt into CredentialProvider one credential at a time
6. Security boundary — explicit trust model for which plugins can provide credentials to which consumers

Prior art

This RFC is directly informed by the production-validated @m1a0rz/agent-identity plugin (Volcengine Agent Identity) — the primary reference implementation demonstrating every capability this RFC proposes to standardize. It provides enterprise-grade credential management through Volcengine's identity service and has been running in production across multi-user gateway deployments.

Key validated patterns: OIDC Authorization Code + PKCE login, per-session credential scoping, STS AssumeRole credential chains, TIP workload JWT, proactive token refresh, per-tool-call env injection with snapshot/restore isolation, skill credential requirements via SKILL.md frontmatter metadata, and graceful degradation.

Design overview

Architecture

┌────────────────────────────────────────────────────────────────────────────────┐
│                             OpenClaw Gateway                                    │
│                                                                                │
│  ┌─────────────┐   ┌──────────────┐   ┌────────────────────────┐              │
│  │   Channel    │   │    Model     │   │   Skill / Tool         │              │
│  │  (consumer)  │   │  (consumer)  │   │   (consumer)           │              │
│  └──────┬───────┘   └──────┬───────┘   └───────┬────────────────┘              │
│         │                  │                    │                               │
│         ▼                  ▼                    ▼                               │
│  ┌──────────────────────────────────────────────────────────────────────┐       │
│  │              Credential Resolution Engine (NEW)                      │       │
│  │                                                                      │       │
│  │  Consumer API:                                                       │       │
│  │    requestCredential(providerId, credentialId, opts)                 │       │
│  │                                                                      │       │
│  │  Lifecycle:                                                          │       │
│  │    resolve() → refresh() → healthCheck() → revoke()                 │       │
│  └────────────────────────────┬─────────────────────────────────────────┘       │
│                               │                                                │
│                               ▼                                                │
│  ┌──────────────────────────────────────────────────────────────┐              │
│  │         Credential Provider Plugin Registry                   │              │
│  │                                                               │              │
│  │  ┌────────────────────┐  ┌──────────────┐  ┌─────────────┐  │              │
│  │  │ Volcengine Identity│  │  Keychain /  │  │  Third-party│  │              │
│  │  │  (OIDC + STS +     │  │  OS secrets  │  │  providers  │  │              │
│  │  │   TIP + risk)      │  │              │  │             │  │              │
│  │  └────────────────────┘  └──────────────┘  └─────────────┘  │              │
│  └──────────────────────────────────────────────────────────────┘              │
│                                                                                │
│  ┌──────────────────────────────────────────────────────────────────────┐       │
│  │              SecretRef System (UNCHANGED)                            │       │
│  │                                                                      │       │
│  │  Sources: env | file | exec                                          │       │
│  │  Behavior: batch resolve at startup, string values, stateless        │       │
│  └──────────────────────────────────────────────────────────────────────┘       │
└────────────────────────────────────────────────────────────────────────────────┘

The two systems compared

Core concepts (summary)

1. Credential Provider Plugin — a new plugin capability with unique providerId, implementing CredentialProvider interface, registered via api.registerCredentialProvider()
2. Credential reference in config — CredentialRef { provider, id } shape distinct from SecretRef
3. Credential types and lifecycle — api_key | oauth2 | token | user_value with full state machine (configure → resolve → active → expiring → refresh → revoke)
4. Relationship with existing model provider auth — ProviderAuthMethod continues unchanged; optional delegation to CredentialProvider
5. Interactive authentication flows — OAuth2/OIDC + Device Code for local/remote gateways
6. Per-session vs per-gateway scoping — gateway-wide for shared credentials, per-session for user-specific tokens
7. Skill credential requirements — declarative CredentialRequirement in SKILL.md frontmatter
8. Credential isolation from LLM context — env injection + contract-based instruction
9. Concurrent credential resolution — deduplication at (providerId, credentialId, sessionKey) level
10. Boundary and bridging with AuthProfileStore / ProviderAuthMethod — three opt-in bridges: delegation, read-through, write-through

Boundary with existing AuthProfileStore / ProviderAuthMethod

The existing AuthProfileStore + ProviderAuthMethod closed loop is intentionally preserved. The two systems operate independently, with three opt-in bridging mechanisms:

┌────────────────────────────────────────────────────────────────────────┐
│                    Model Provider Auth (existing)                      │
│                                                                        │
│  ProviderAuthMethod  ──▶  AuthProfileStore  ──▶  prepareRuntimeAuth   │
│  (setup/onboard)         (auth-profiles.json)    (inference-time)      │
│                                                                        │
│  Scope: model providers only                                           │
│  Storage: file-backed per-agent JSON                                   │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ (opt-in bridging)
┌───────────────────────────────────▼────────────────────────────────────┐
│                    Credential Provider (new)                            │
│                                                                        │
│  CredentialProvider  ──▶  Credential Resolution Engine  ──▶  consumers │
│  (plugin registration)   (in-memory cache + lifecycle)   (any domain)  │
│                                                                        │
│  Scope: models, channels, skills, tools, plugins                       │
│  Storage: in-memory (CredentialRef pointers in config)                  │
└────────────────────────────────────────────────────────────────────────┘

• Bridge 1: ProviderAuthMethod.credentialProvider delegation — model provider delegates auth to a CredentialProvider
• Bridge 2: AuthProfileStore as a CredentialProvider backend — expose existing profiles to non-model consumers
• Bridge 3: CredentialRef → AuthProfileStore write-through — resolved credentials upserted as synthetic profiles

Migration phases

1. Phase 1 (this RFC): CredentialProvider interface + Plugin SDK + CredentialResolutionEngine + openclaw credentials CLI
2. Phase 2: Migrate agent-identity-plugin as reference; ship @openclaw/keychain-provider
3. Phase 3: Consumer integration (CredentialRef in model/channel/tool config) + skill metadata standardization
4. Phase 4: Advanced lifecycle (refresh scheduler, health monitoring, rotation event bus)

Backward compatibility

All existing behavior is unchanged: SecretRef, ProviderAuthMethod, AuthProfileStore, channel setup adapters, and third-party plugins continue working without modification.

Full proposal

The complete RFC (80 KB) with detailed interface definitions, TypeScript code examples, security model, error handling, CLI integration, open questions (17 items), and three appendices is available at:

https://gist.github.com/loveyana/a42c4bc48f71fdac772a09db02d9a802

Feedback welcome on any section — especially the open questions around consumer adoption path, credential caching, and the AuthProfileStore bridging mechanisms.