> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Kontrak rencana penerapan rahasia

Halaman ini mendefinisikan kontrak ketat yang diberlakukan oleh `openclaw secrets apply`.

Jika sebuah target tidak cocok dengan aturan ini, apply gagal sebelum memutasi konfigurasi.

## Bentuk file rencana

`openclaw secrets apply --from <plan.json>` mengharapkan array `targets` berisi target rencana:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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" },
    },
  ],
}
```

## Upsert dan penghapusan penyedia

Rencana juga dapat menyertakan dua field tingkat atas opsional yang memutasi peta
`secrets.providers` bersama penulisan per target:

* `providerUpserts` — objek yang dikunci berdasarkan alias penyedia. Setiap nilai adalah
  definisi penyedia (bentuk yang sama yang diterima di bawah
  `secrets.providers.<alias>` dalam `openclaw.json`, misalnya penyedia `exec` atau `file`).
* `providerDeletes` — array alias penyedia yang akan dihapus.

`providerUpserts` berjalan sebelum `targets`, sehingga `target.ref.provider` dapat
mereferensikan alias penyedia yang diperkenalkan oleh rencana yang sama dalam
`providerUpserts`. Tanpa ini, rencana yang mereferensikan alias yang belum
dikonfigurasi dalam `openclaw.json` gagal dengan `provider "<alias>" is not
configured`.

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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" },
    },
  ],
}
```

Penyedia exec yang diperkenalkan melalui `providerUpserts` tetap tunduk pada
aturan persetujuan exec dalam [Perilaku persetujuan penyedia exec](#exec-provider-consent-behavior):
rencana yang berisi penyedia exec memerlukan `--allow-exec` dalam mode tulis.

## Cakupan target yang didukung

Target rencana diterima untuk jalur kredensial yang didukung dalam:

* [Permukaan Kredensial SecretRef](/id/reference/secretref-credential-surface)

## Perilaku jenis target

Aturan umum:

* `target.type` harus dikenali dan harus cocok dengan bentuk `target.path` yang dinormalisasi.

Alias kompatibilitas tetap diterima untuk rencana yang sudah ada:

* `models.providers.apiKey`
* `skills.entries.apiKey`
* `channels.googlechat.serviceAccount`

## Aturan validasi jalur

Setiap target divalidasi dengan semua aturan berikut:

* `type` harus berupa jenis target yang dikenali.
* `path` harus berupa jalur titik yang tidak kosong.
* `pathSegments` dapat dihilangkan. Jika disediakan, nilainya harus dinormalisasi menjadi jalur yang persis sama dengan `path`.
* Segmen terlarang ditolak: `__proto__`, `prototype`, `constructor`.
* Jalur yang dinormalisasi harus cocok dengan bentuk jalur terdaftar untuk jenis target.
* Jika `providerId` atau `accountId` diatur, nilainya harus cocok dengan id yang dikodekan dalam jalur.
* Target `auth-profiles.json` memerlukan `agentId`.
* Saat membuat pemetaan `auth-profiles.json` baru, sertakan `authProfileProvider`.

## Perilaku kegagalan

Jika sebuah target gagal validasi, apply keluar dengan error seperti:

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
Invalid plan target path for models.providers.apiKey: models.providers.openai.baseUrl
```

Tidak ada penulisan yang dikomit untuk rencana yang tidak valid.

## Perilaku persetujuan penyedia exec

* `--dry-run` melewati pemeriksaan exec SecretRef secara default.
* Rencana yang berisi exec SecretRefs/penyedia ditolak dalam mode tulis kecuali `--allow-exec` diatur.
* Saat memvalidasi/menerapkan rencana yang berisi exec, berikan `--allow-exec` dalam perintah dry-run dan tulis.

## Catatan cakupan runtime dan audit

* Entri `auth-profiles.json` yang hanya ref (`keyRef`/`tokenRef`) disertakan dalam resolusi runtime dan cakupan audit.
* `secrets apply` menulis target `openclaw.json` yang didukung, target `auth-profiles.json` yang didukung, dan target scrub opsional.

## Pemeriksaan operator

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 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
```

Jika apply gagal dengan pesan jalur target yang tidak valid, buat ulang rencana dengan `openclaw secrets configure` atau perbaiki jalur target ke bentuk yang didukung di atas.

## Dokumen terkait

* [Manajemen Secrets](/id/gateway/secrets)
* [CLI `secrets`](/id/cli/secrets)
* [Permukaan Kredensial SecretRef](/id/reference/secretref-credential-surface)
* [Referensi Konfigurasi](/id/gateway/configuration-reference)