Secrets apply plan contract

This page defines the strict contract enforced by

.

If a target does not match these rules, apply fails before mutating configuration.

Plan file shape

expects a array of plan targets:

json5
Copy
{
  version: 1,
  protocolVersion: 1,
  targets: [
    {
      type: "models.providers.apiKey",
      path: "models.providers.openai.apiKey",
      pathSegments: ["models", "providers", "openai", "apiKey"],
      providerId: "openai",
      ref: { source: "env", provider: "default", id: "OPENAI_API_KEY" },
    },
    {
      type: "auth-profiles.api_key.key",
      path: "profiles.openai:default.key",
      pathSegments: ["profiles", "openai:default", "key"],
      agentId: "main",
      ref: { source: "env", provider: "default", id: "OPENAI_API_KEY" },
    },
  ],
}

Supported target scope

Plan targets are accepted for supported credential paths in:

• SecretRef Credential Surface

Target type behavior

General rule:

• text

  Copy

  target.type
  must be recognized and must match the normalized
  text

  Copy

  target.path
  shape.

Compatibility aliases remain accepted for existing plans:

• text

  Copy

  models.providers.apiKey
• text

  Copy

  skills.entries.apiKey
• text

  Copy

  channels.googlechat.serviceAccount

Path validation rules

Each target is validated with all of the following:

• text

  Copy

  type
  must be a recognized target type.
• text

  Copy

  path
  must be a non-empty dot path.
• text

  Copy

  pathSegments
  can be omitted. If provided, it must normalize to exactly the same path as
  text

  Copy

  path
  .
• Forbidden segments are rejected:
  text

  Copy

  __proto__
  ,
  text

  Copy

  prototype
  ,
  text

  Copy

  constructor
  .
• The normalized path must match the registered path shape for the target type.
• If
  text

  Copy

  providerId
  or
  text

  Copy

  accountId
  is set, it must match the id encoded in the path.
• text

  Copy

  auth-profiles.json
  targets require
  text

  Copy

  agentId
  .
• When creating a new
  text

  Copy

  auth-profiles.json
  mapping, include
  text

  Copy

  authProfileProvider
  .

Failure behavior

If a target fails validation, apply exits with an error like:

text
Copy
Invalid plan target path for models.providers.apiKey: models.providers.openai.baseUrl

No writes are committed for an invalid plan.

Exec provider consent behavior

• text

  Copy

  --dry-run
  skips exec SecretRef checks by default.
• Plans containing exec SecretRefs/providers are rejected in write mode unless
  text

  Copy

  --allow-exec
  is set.
• When validating/applying exec-containing plans, pass
  text

  Copy

  --allow-exec
  in both dry-run and write commands.

Runtime and audit scope notes

• Ref-only
  text

  Copy

  auth-profiles.json
  entries (
  text

  Copy

  keyRef
  /
  text

  Copy

  tokenRef
  ) are included in runtime resolution and audit coverage.
• text

  Copy

  secrets apply
  writes supported
  text

  Copy

  openclaw.json
  targets, supported
  text

  Copy

  auth-profiles.json
  targets, and optional scrub targets.

Operator checks

bash
Copy
# Validate plan without writes
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run

# Then apply for real
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json

# For exec-containing plans, opt in explicitly in both modes
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec

If apply fails with an invalid target path message, regenerate the plan with

or fix the target path to a supported shape above.

Related docs

• Secrets Management
• CLI
  text

  Copy

  secrets
• SecretRef Credential Surface
• Configuration Reference