Secrets apply plan contract

Secrets apply plan contract 문서는 OpenClaw 공식 문서(gateway/secrets-plan-contract)를 한국어로 정리한 가이드입니다. Contract for secrets apply plans: target validation, path matching, and auth-profiles.json target scope 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Contract for secrets apply plans: target validation, path matching, and auth-profiles.json target scope

한국어 가이드 범위: gateway/secrets-plan-contract 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Plan file requirements
Plan file shape
Provider upserts and deletes
Supported target scope
Target type behavior
Path validation rules
Failure behavior
Exec provider consent behavior
Runtime and audit scope notes
Operator checks
Validate plan without writes
Then apply for real
For exec-containing plans, opt in explicitly in both modes
Related docs

상세 내용

본문

This page defines the strict contract enforced by openclaw secrets apply. If a target does not match these rules, apply fails before mutating any file.

Plan file requirements

openclaw secrets apply --from accepts regular files up to 16 MiB (16,777,216 bytes). The limit applies to the complete serialized file, including whitespace. Directories, FIFOs, device files, and files larger than the limit are rejected before JSON parsing or target validation.

Plan file shape

openclaw secrets apply --from expects a targets array of plan targets:

{
  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" },
    },
  ],
}

Provider upserts and deletes

Plans may also include two optional top-level fields that mutate the secrets.providers map alongside the per-target writes:

주요 항목:

providerUpserts -- an object keyed by provider alias. Each value is a provider definition (the same shape accepted under secrets.providers.<alias> in openclaw.json, e.g. an exec or file provider).
providerDeletes -- an array of provider aliases to remove.

{
  version: 1,
  protocolVersion: 1,
  providerUpserts: {
    onepassword_anthropic: {
      source: "exec",
      command: "/usr/bin/op",
      args: ["read", "op://Vault/Anthropic/credential"],
    },
  },
  providerDeletes: ["legacy_unused_alias"],
  targets: [
    {
      type: "models.providers.apiKey",
      path: "models.providers.anthropic.apiKey",
      pathSegments: ["models", "providers", "anthropic", "apiKey"],
      providerId: "anthropic",
      ref: { source: "exec", provider: "onepassword_anthropic", id: "credential" },
    },
  ],
}

Supported target scope

Plan targets are accepted for supported credential paths in SecretRef Credential Surface.

Target type behavior

target.type must be a recognized target type, and the normalized target.path must match that type's registered path shape.

Canonical type	Accepted alias
`models.providers.apiKey`	`models.providers.*.apiKey`
`skills.entries.apiKey`	`skills.entries.*.apiKey`
`channels.googlechat.serviceAccount`	`channels.googlechat.accounts.*.serviceAccount`

Path validation rules

Each target is validated with all of the following:

주요 항목:

type must be a recognized target type.
path must be a non-empty dot path.
pathSegments can be omitted. If provided, it must normalize to exactly the same path as path.
Forbidden segments are rejected: __proto__, prototype, constructor.
The normalized path must match the registered path shape for the target type.
If providerId or accountId is set, it must match the id encoded in the path.
auth-profiles.json targets require agentId.
When creating a new auth-profiles.json mapping, include authProfileProvider.

Failure behavior

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

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

주요 항목:

--dry-run skips exec SecretRef checks by default.
Plans containing exec SecretRefs/providers are rejected in write mode unless --allow-exec is set.
When validating/applying exec-containing plans, pass --allow-exec in both dry-run and write commands.

Runtime and audit scope notes

주요 항목:

Ref-only auth-profiles.json entries (keyRef/tokenRef) are included in runtime credential resolution and audit coverage.
secrets apply writes supported openclaw.json targets, supported auth-profiles.json targets, and three optional scrub passes, each on by default: scrubEnv (removes migrated plaintext values from .env files in the effective state and active-config directories), scrubAuthProfilesForProviderTargets (clears plaintext/unused-ref residue in auth-profiles.json for providers a plan just migrated), and scrubLegacyAuthJson (drops migrated api_key entries from legacy auth.json stores). Set any of options.scrubEnv, options.scrubAuthProfilesForProviderTargets, options.scrubLegacyAuthJson to false in the plan to skip that pass.

Operator checks


### Validate plan without writes

openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

### Then apply for real

openclaw secrets apply --from /tmp/openclaw-secrets-plan.json

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

### 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 ```

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

### Related docs

주요 항목:

- Secrets Management
- CLI `secrets`
- SecretRef Credential Surface
- Configuration Reference

## 실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: `https://docs.openclaw.ai/gateway/secrets-plan-contract`
2. 관련 CLI는 `openclaw --help` 및 하위 명령 `--help`로 옵션을 확인합니다.
3. 설정 변경 시 `openclaw config` / `openclaw doctor`로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

## 자주 쓰는 명령·설정 예시

```json5
{
  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" },
    },
  ],
}

{
  version: 1,
  protocolVersion: 1,
  providerUpserts: {
    onepassword_anthropic: {
      source: "exec",
      command: "/usr/bin/op",
      args: ["read", "op://Vault/Anthropic/credential"],
    },
  },
  providerDeletes: ["legacy_unused_alias"],
  targets: [
    {
      type: "models.providers.apiKey",
      path: "models.providers.anthropic.apiKey",
      pathSegments: ["models", "providers", "anthropic", "apiKey"],
      providerId: "anthropic",
      ref: { source: "exec", provider: "onepassword_anthropic", id: "credential" },
    },
  ],
}

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

# 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

Secrets apply plan contract

핵심 요약

Contract for secrets apply plans: target validation, path matching, and auth-profiles.json target scope

한국어 가이드 범위: gateway/secrets-plan-contract 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Plan file requirements
Plan file shape
Provider upserts and deletes
Supported target scope
Target type behavior
Path validation rules
Failure behavior
Exec provider consent behavior
Runtime and audit scope notes
Operator checks
Validate plan without writes
Then apply for real
For exec-containing plans, opt in explicitly in both modes
Related docs

상세 내용

본문

This page defines the strict contract enforced by openclaw secrets apply. If a target does not match these rules, apply fails before mutating any file.

Plan file requirements

Plan file shape

openclaw secrets apply --from expects a targets array of plan targets:

{
  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" },
    },
  ],
}

Provider upserts and deletes

Plans may also include two optional top-level fields that mutate the secrets.providers map alongside the per-target writes:

주요 항목:

providerUpserts -- an object keyed by provider alias. Each value is a provider definition (the same shape accepted under secrets.providers.<alias> in openclaw.json, e.g. an exec or file provider).
providerDeletes -- an array of provider aliases to remove.

{
  version: 1,
  protocolVersion: 1,
  providerUpserts: {
    onepassword_anthropic: {
      source: "exec",
      command: "/usr/bin/op",
      args: ["read", "op://Vault/Anthropic/credential"],
    },
  },
  providerDeletes: ["legacy_unused_alias"],
  targets: [
    {
      type: "models.providers.apiKey",
      path: "models.providers.anthropic.apiKey",
      pathSegments: ["models", "providers", "anthropic", "apiKey"],
      providerId: "anthropic",
      ref: { source: "exec", provider: "onepassword_anthropic", id: "credential" },
    },
  ],
}

Supported target scope

Plan targets are accepted for supported credential paths in SecretRef Credential Surface.

Target type behavior

target.type must be a recognized target type, and the normalized target.path must match that type's registered path shape.

Canonical type	Accepted alias
`models.providers.apiKey`	`models.providers.*.apiKey`
`skills.entries.apiKey`	`skills.entries.*.apiKey`
`channels.googlechat.serviceAccount`	`channels.googlechat.accounts.*.serviceAccount`

Path validation rules

Each target is validated with all of the following:

주요 항목:

type must be a recognized target type.
path must be a non-empty dot path.
pathSegments can be omitted. If provided, it must normalize to exactly the same path as path.
Forbidden segments are rejected: __proto__, prototype, constructor.
The normalized path must match the registered path shape for the target type.
If providerId or accountId is set, it must match the id encoded in the path.
auth-profiles.json targets require agentId.
When creating a new auth-profiles.json mapping, include authProfileProvider.

Failure behavior

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

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

주요 항목:

--dry-run skips exec SecretRef checks by default.
Plans containing exec SecretRefs/providers are rejected in write mode unless --allow-exec is set.
When validating/applying exec-containing plans, pass --allow-exec in both dry-run and write commands.

Runtime and audit scope notes

주요 항목:

Ref-only auth-profiles.json entries (keyRef/tokenRef) are included in runtime credential resolution and audit coverage.
secrets apply writes supported openclaw.json targets, supported auth-profiles.json targets, and three optional scrub passes, each on by default: scrubEnv (removes migrated plaintext values from .env files in the effective state and active-config directories), scrubAuthProfilesForProviderTargets (clears plaintext/unused-ref residue in auth-profiles.json for providers a plan just migrated), and scrubLegacyAuthJson (drops migrated api_key entries from legacy auth.json stores). Set any of options.scrubEnv, options.scrubAuthProfilesForProviderTargets, options.scrubLegacyAuthJson to false in the plan to skip that pass.

Operator checks


### Validate plan without writes

openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

### Then apply for real

openclaw secrets apply --from /tmp/openclaw-secrets-plan.json

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

### 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 ```

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

### Related docs

주요 항목:

- Secrets Management
- CLI `secrets`
- SecretRef Credential Surface
- Configuration Reference

## 실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: `https://docs.openclaw.ai/gateway/secrets-plan-contract`
2. 관련 CLI는 `openclaw --help` 및 하위 명령 `--help`로 옵션을 확인합니다.
3. 설정 변경 시 `openclaw config` / `openclaw doctor`로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

## 자주 쓰는 명령·설정 예시

```json5
{
  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" },
    },
  ],
}

{
  version: 1,
  protocolVersion: 1,
  providerUpserts: {
    onepassword_anthropic: {
      source: "exec",
      command: "/usr/bin/op",
      args: ["read", "op://Vault/Anthropic/credential"],
    },
  },
  providerDeletes: ["legacy_unused_alias"],
  targets: [
    {
      type: "models.providers.apiKey",
      path: "models.providers.anthropic.apiKey",
      pathSegments: ["models", "providers", "anthropic", "apiKey"],
      providerId: "anthropic",
      ref: { source: "exec", provider: "onepassword_anthropic", id: "credential" },
    },
  ],
}

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

# 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

Secrets apply plan contract

핵심 요약

문서 구성

상세 내용

본문

Plan file requirements

Plan file shape

Provider upserts and deletes

Supported target scope

Target type behavior

Path validation rules

Failure behavior

Runtime and audit scope notes

Operator checks

관련 링크

관련 가이드

Secrets apply plan contract

핵심 요약

문서 구성

상세 내용

본문

Plan file requirements

Plan file shape

Provider upserts and deletes

Supported target scope

Target type behavior

Path validation rules

Failure behavior

Runtime and audit scope notes

Operator checks

관련 링크

관련 가이드

Secrets apply plan contract

핵심 요약

문서 구성

상세 내용

본문

Plan file requirements

Plan file shape

Provider upserts and deletes

Supported target scope

Target type behavior

Path validation rules

Failure behavior

Exec provider consent behavior

Runtime and audit scope notes

Operator checks

관련 링크

관련 가이드

Secrets apply plan contract

핵심 요약

문서 구성

상세 내용

본문

Plan file requirements

Plan file shape

Provider upserts and deletes

Supported target scope

Target type behavior

Path validation rules

Failure behavior

Exec provider consent behavior

Runtime and audit scope notes

Operator checks

관련 링크

관련 가이드