<!-- source: https://deepwiki.com/openclaw/openclaw/7.4-secret-management -->

# Secret Management

- extensions/memory-core/cli-metadata.ts
- extensions/memory-core/cli.ts
- scripts/repro/cli-web-search-secret-refs-live-proof.mjs
- src/acp/client-helpers.ts
- src/acp/client.test.ts
- src/agents/model-auth-env-vars.ts
- src/agents/models-config.providers.moonshot.test.ts
- src/agents/models-config.providers.nvidia.test.ts
- src/agents/models-config.runtime-source-snapshot.test.ts
- src/cli/capability-cli.test.ts
- src/cli/capability-cli.ts
- src/cli/command-config-resolution.test.ts
- src/cli/command-config-resolution.ts
- src/cli/command-secret-gateway.test.ts
- src/cli/command-secret-gateway.ts
- src/cli/command-secret-resolution.coverage.test.ts
- src/cli/command-secret-targets.import.test.ts
- src/cli/command-secret-targets.test.ts
- src/cli/command-secret-targets.ts
- src/cli/plugins-install-record-commit.ts
- src/commands/agents.bind.test-support.ts
- src/commands/models/load-config.test.ts
- src/commands/models/load-config.ts
- src/config/config.ts
- src/config/doc-baseline.integration.test.ts
- src/config/io.ts
- src/config/io.write-config.test.ts
- src/config/mutate.test.ts
- src/config/mutate.ts
- src/config/runtime-snapshot.ts
- src/config/session-parent-fork-config-keys.test.ts
- src/gateway/server-aux-handlers.ts
- src/gateway/server-methods/config-write-flow.ts
- src/gateway/server-methods/config.shared-auth.test.ts
- src/gateway/server-methods/secrets.ts
- src/gateway/server-startup-config.ts
- src/secrets/runtime-command-secrets.test.ts
- src/secrets/runtime-command-secrets.ts
- src/secrets/runtime-fast-path.ts
- src/secrets/runtime-request-secret-refs.test.ts
- src/secrets/runtime-secret-scan.ts
- src/secrets/runtime-web-tools.test.ts
- src/secrets/runtime-web-tools.ts
- src/secrets/runtime.gateway-auth.integration.test.ts
- src/secrets/runtime.test.ts
- src/secrets/runtime.ts

OpenClaw provides a comprehensive and secure secret management system that handles sensitive credentials such as API keys, tokens, and passwords using a flexible and unified abstraction called `SecretRef`. This system cleanly separates secret references from actual secret values, enabling support for multiple secret backends, safe credential rotation, per-environment overrides, and secure storage across agent workspaces without embedding secrets directly in the configuration.

## SecretRef System

The foundation of OpenClaw's secret management is the `SecretRef` abstraction, a structure that explicitly describes how and where a secret is sourced. This uniform interface is leveraged throughout OpenClaw for model providers, messaging channels, and internal gateway authentication.

### Supported Secret Sources

- Environment Variables ( env ) : Secrets can reference environment variables by name. This method supports injection of secrets via standard environment variable workflows. The getProviderEnvVars function is used to identify standard environment variable names based on provider IDs src/cli/capability-cli.ts 77
- Auth Profiles : Credentials stored in auth-profiles.json . The system can discover and load these profiles using loadAuthProfileStoreForRuntime src/cli/capability-cli.ts 23
- Implicit Discovery : OpenClaw can detect credentials from conventional environment variables. The resolveApiKeyForProvider function handles the resolution logic for these providers src/cli/capability-cli.ts 29
- Runtime Web Tools : Web search and fetch providers (like Brave, Tavily, or Firecrawl) resolve their API keys through a specialized resolveRuntimeWebTools pipeline that checks both configuration and environment variables src/secrets/runtime-web-tools.ts 70

### Structure and Resolution

Validation and resolution of these secrets are integrated into the CLI and Gateway startup. OpenClaw resolves command configuration secrets via the helper `resolveCommandConfigWithSecrets` function to transparently inject secrets into CLI commands [src/cli/capability-cli.ts105](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/capability-cli.ts#L105-L105)

**Sources:**
[src/cli/capability-cli.ts23](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/capability-cli.ts#L23-L23) [src/cli/capability-cli.ts29](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/capability-cli.ts#L29-L29) [src/cli/capability-cli.ts77](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/capability-cli.ts#L77-L77) [src/cli/capability-cli.ts105](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/capability-cli.ts#L105-L105) [src/secrets/runtime-web-tools.ts70](https://github.com/openclaw/openclaw/blob/fbdf5937/src/secrets/runtime-web-tools.ts#L70-L70)

## Secret Resolution Flow

Secrets are resolved into concrete values during runtime through a structured pipeline. This process is designed to guarantee startup-time validation and consistent secret updates.

### Runtime Snapshot Model

- Startup Preparation : During Gateway startup, loadGatewayStartupConfigSnapshot coordinates the initial validation and resolution of secrets src/gateway/server-startup-config.ts 104-109
- Activation Lifecycle : The system uses createRuntimeSecretsActivator to create a serialized activation function used during startup and configuration reloads src/gateway/server-startup-config.ts 170-181
- Fast Path Snapshots : For performance, the system can prepare a "fast path" snapshot of secrets using prepareSecretsRuntimeFastPathSnapshot src/gateway/server-startup-config.ts 22-24

### Secret Resolution Engine Diagram

```

```

**Diagram Title: Secret Resolution Engine Flow**

**Sources:**
[src/gateway/server-startup-config.ts22-34](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-startup-config.ts#L22-L34) [src/gateway/server-startup-config.ts104-109](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-startup-config.ts#L104-L109) [src/gateway/server-startup-config.ts170-181](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-startup-config.ts#L170-L181) [src/cli/capability-cli.ts23-29](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/capability-cli.ts#L23-L29) [src/cli/capability-cli.ts77](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/capability-cli.ts#L77-L77) [src/secrets/runtime-web-tools.ts70](https://github.com/openclaw/openclaw/blob/fbdf5937/src/secrets/runtime-web-tools.ts#L70-L70)

## Auth Profiles & Credential Storage

OpenClaw uses **Auth Profiles** to manage and persist credentials for model providers. Credentials are stored in a structured store and managed via dedicated utility functions.

### Profile Management

- Store Loading : Profiles are loaded from disk using loadAuthProfileStoreForRuntime src/cli/capability-cli.ts 23
- Atomic Updates : Updates to the profile store are performed with a lock to prevent corruption using updateAuthProfileStoreWithLock src/cli/capability-cli.ts 25
- Provider Filtering : The CLI can list profiles associated with a specific provider using listProfilesForProvider src/cli/capability-cli.ts 22

### Credential Resolution Hierarchy

When an agent or tool needs to call a service, it follows this resolution path:

1. Direct API Key : Checking for keys directly in configuration or resolved via resolveApiKeyForProvider src/cli/capability-cli.ts 29
2. Auth Profile Store : Retrieving a stored profile for the specific provider src/cli/capability-cli.ts 23-24
3. Implicit Env : Falling back to provider-specific defaults like OPENAI_API_KEY identified via getProviderEnvVars src/cli/capability-cli.ts 77

**Sources:**
[src/cli/capability-cli.ts22-25](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/capability-cli.ts#L22-L25) [src/cli/capability-cli.ts29](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/capability-cli.ts#L29-L29) [src/cli/capability-cli.ts77](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/capability-cli.ts#L77-L77)

## Secret Auditing and Diagnostics

OpenClaw includes diagnostic tools to ensure secrets are correctly configured and not leaked.

### Command Secret Targets

The system defines specific "secret target IDs" which are configuration paths known to contain sensitive data. These are used to identify which parts of the configuration should be treated as secrets:

- Models : models.providers.*.apiKey src/cli/command-secret-targets.ts 23
- Gateway Auth : gateway.auth.token and gateway.auth.password src/cli/command-secret-targets.ts 58-59
- Plugin Credentials : The system identifies plugin-specific credentials for web search and fetch using isPluginWebSearchCredentialTargetId and isPluginWebFetchCredentialTargetId src/cli/command-secret-targets.ts 124-138

### Configuration Health and Audit

- Audit Records : Every config write can generate an audit record via appendConfigAuditRecord src/config/io.ts 48-49
- Health Fingerprinting : The system tracks ConfigHealthFingerprint to detect suspicious modifications or corruption of sensitive configuration files src/config/io.ts 153-167
- Secret Scanning : During runtime, the system can perform scans to ensure no raw secrets are accidentally exposed in non-secret fields src/secrets/runtime-secret-scan.ts

**Sources:**
[src/cli/command-secret-targets.ts23-36](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/command-secret-targets.ts#L23-L36) [src/cli/command-secret-targets.ts58-62](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/command-secret-targets.ts#L58-L62) [src/cli/command-secret-targets.ts124-138](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/command-secret-targets.ts#L124-L138) [src/config/io.ts48-55](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/io.ts#L48-L55) [src/config/io.ts153-167](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/io.ts#L153-L167)

## Code Entity Space Mapping

### Secret Configuration and Discovery

```

```

### Startup Secret Activation

```

```

**Sources:**
[src/gateway/server-startup-config.ts17-24](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-startup-config.ts#L17-L24) [src/gateway/server-startup-config.ts104-109](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-startup-config.ts#L104-L109) [src/gateway/server-startup-config.ts170-181](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-startup-config.ts#L170-L181) [src/cli/capability-cli.ts23-25](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/capability-cli.ts#L23-L25) [src/cli/capability-cli.ts77](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/capability-cli.ts#L77-L77) [src/cli/capability-cli.ts105](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/capability-cli.ts#L105-L105) [src/secrets/runtime-web-tools.ts70](https://github.com/openclaw/openclaw/blob/fbdf5937/src/secrets/runtime-web-tools.ts#L70-L70)
