Manajemen rahasia

OpenClaw mendukung SecretRef aditif sehingga kredensial yang didukung tidak perlu disimpan sebagai teks polos dalam konfigurasi.

# Tujuan dan model runtime

Secret diselesaikan menjadi snapshot runtime dalam memori.

• Resolusi dilakukan secara eager saat aktivasi, bukan lazy pada jalur permintaan.
• Startup gagal cepat ketika SecretRef yang secara efektif aktif tidak dapat diselesaikan.
• Reload menggunakan pertukaran atomik: berhasil penuh, atau tetap memakai snapshot terakhir yang diketahui baik.
• Pelanggaran kebijakan SecretRef (misalnya profil autentikasi mode OAuth yang digabungkan dengan input SecretRef) menggagalkan aktivasi sebelum pertukaran runtime.
• Permintaan runtime hanya membaca dari snapshot dalam memori yang aktif.
• Setelah aktivasi/pemuatan konfigurasi pertama berhasil, jalur kode runtime terus membaca snapshot dalam memori aktif tersebut hingga reload yang berhasil menukarnya.
• Jalur pengiriman keluar juga membaca dari snapshot aktif tersebut (misalnya pengiriman balasan/thread Discord dan pengiriman aksi Telegram); jalur ini tidak menyelesaikan ulang SecretRef pada setiap pengiriman.

Ini menjaga gangguan penyedia secret tetap berada di luar jalur permintaan panas.

# Pemfilteran permukaan aktif

SecretRef hanya divalidasi pada permukaan yang secara efektif aktif.

• Permukaan aktif: referensi yang belum terselesaikan memblokir startup/reload.
• Permukaan tidak aktif: referensi yang belum terselesaikan tidak memblokir startup/reload.
• Referensi tidak aktif memancarkan diagnostik non-fatal dengan kode SECRETS_REF_IGNORED_INACTIVE_SURFACE.

# Diagnostik permukaan autentikasi Gateway

Ketika SecretRef dikonfigurasi pada gateway.auth.token, gateway.auth.password, gateway.remote.token, atau gateway.remote.password, startup/reload gateway mencatat status permukaan secara eksplisit:

• active: SecretRef adalah bagian dari permukaan autentikasi efektif dan harus diselesaikan.
• inactive: SecretRef diabaikan untuk runtime ini karena permukaan autentikasi lain menang, atau karena autentikasi remote dinonaktifkan/tidak aktif.

Entri ini dicatat dengan SECRETS_GATEWAY_AUTH_SURFACE dan menyertakan alasan yang digunakan oleh kebijakan permukaan aktif, sehingga Anda dapat melihat mengapa kredensial diperlakukan sebagai aktif atau tidak aktif.

# Preflight referensi onboarding

Ketika onboarding berjalan dalam mode interaktif dan Anda memilih penyimpanan SecretRef, OpenClaw menjalankan validasi preflight sebelum menyimpan:

• Referensi env: memvalidasi nama variabel env dan mengonfirmasi nilai tidak kosong terlihat selama penyiapan.
• Referensi penyedia (file atau exec): memvalidasi pilihan penyedia, menyelesaikan id, dan memeriksa tipe nilai yang diselesaikan.
• Jalur penggunaan ulang quickstart: ketika gateway.auth.token sudah berupa SecretRef, onboarding menyelesaikannya sebelum bootstrap probe/dashboard (untuk referensi env, file, dan exec) menggunakan gerbang gagal-cepat yang sama.

Jika validasi gagal, onboarding menampilkan kesalahan dan memungkinkan Anda mencoba lagi.

# Kontrak SecretRef

Gunakan satu bentuk objek di mana saja:

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

{ source: "env", provider: "default", id: "OPENAI_API_KEY" }

{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }

{ source: "exec", provider: "vault", id: "providers/openai/apiKey" }

# Konfigurasi penyedia

Definisikan penyedia di bawah secrets.providers:

{
  secrets: {
    providers: {
      default: { source: "env" },
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json", // or "singleValue"
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        args: ["--profile", "prod"],
        passEnv: ["PATH", "VAULT_ADDR"],
        jsonOnly: true,
      },
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault",
    },
    resolution: {
      maxProviderConcurrency: 4,
      maxRefsPerProvider: 512,
      maxBatchBytes: 262144,
    },
  },
}

{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }

{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "<openai-api-key>" } } // pragma: allowlist secret

{
  "protocolVersion": 1,
  "values": {},
  "errors": { "providers/openai/apiKey": { "message": "not found" } }
}

# Contoh integrasi exec

{
  secrets: {
    providers: {
      onepassword_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/op",
        allowSymlinkCommand: true, // required for Homebrew symlinked binaries
        trustedDirs: ["/opt/homebrew"],
        args: ["read", "op://Personal/OpenClaw QA API Key/password"],
        passEnv: ["HOME"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "onepassword_openai", id: "value" },
      },
    },
  },
}

{
  secrets: {
    providers: {
      vault_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/vault",
        allowSymlinkCommand: true, // required for Homebrew symlinked binaries
        trustedDirs: ["/opt/homebrew"],
        args: ["kv", "get", "-field=OPENAI_API_KEY", "secret/openclaw"],
        passEnv: ["VAULT_ADDR", "VAULT_TOKEN"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "vault_openai", id: "value" },
      },
    },
  },
}

{
  secrets: {
    providers: {
      sops_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/sops",
        allowSymlinkCommand: true, // required for Homebrew symlinked binaries
        trustedDirs: ["/opt/homebrew"],
        args: ["-d", "--extract", '["providers"]["openai"]["apiKey"]', "/path/to/secrets.enc.json"],
        passEnv: ["SOPS_AGE_KEY_FILE"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "sops_openai", id: "value" },
      },
    },
  },
}

# Variabel lingkungan server MCP

Variabel env server MCP yang dikonfigurasi melalui plugins.entries.acpx.config.mcpServers mendukung SecretInput. Ini menjaga kunci API dan token tetap di luar konfigurasi teks polos:

{
  plugins: {
    entries: {
      acpx: {
        enabled: true,
        config: {
          mcpServers: {
            github: {
              command: "npx",
              args: ["-y", "@modelcontextprotocol/server-github"],
              env: {
                GITHUB_PERSONAL_ACCESS_TOKEN: {
                  source: "env",
                  provider: "default",
                  id: "MCP_GITHUB_PAT",
                },
              },
            },
          },
        },
      },
    },
  },
}

Nilai string teks polos tetap berfungsi. Referensi template env seperti ${MCP_SERVER_API_KEY} dan objek SecretRef diselesaikan selama aktivasi gateway sebelum proses server MCP dibuat. Seperti permukaan SecretRef lainnya, referensi yang belum terselesaikan hanya memblokir aktivasi ketika Plugin acpx secara efektif aktif.

# Material autentikasi SSH sandbox

Backend sandbox inti ssh juga mendukung SecretRef untuk material autentikasi SSH:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "ssh",
        ssh: {
          target: "user@gateway-host:22",
          identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
      },
    },
  },
}

Perilaku runtime:

• OpenClaw menyelesaikan ref ini selama aktivasi sandbox, bukan secara malas pada setiap panggilan SSH.
• Nilai yang diselesaikan ditulis ke file sementara dengan izin ketat dan digunakan dalam konfigurasi SSH yang dihasilkan.
• Jika backend sandbox efektif bukan ssh, ref ini tetap tidak aktif dan tidak memblokir startup.

# Permukaan kredensial yang didukung

Kredensial kanonis yang didukung dan tidak didukung tercantum di:

• Permukaan Kredensial SecretRef

# Perilaku wajib dan prioritas

• Field tanpa ref: tidak berubah.
• Field dengan ref: wajib pada permukaan aktif selama aktivasi.
• Jika plaintext dan ref sama-sama ada, ref diprioritaskan pada jalur prioritas yang didukung.
• Sentinel redaksi __OPENCLAW_REDACTED__ dicadangkan untuk redaksi/pemulihan konfigurasi internal dan ditolak sebagai data konfigurasi literal yang dikirimkan.

Sinyal peringatan dan audit:

• SECRETS_REF_OVERRIDES_PLAINTEXT (peringatan runtime)
• REF_SHADOWED (temuan audit saat kredensial auth-profiles.json diprioritaskan dibanding ref openclaw.json)

Perilaku kompatibilitas Google Chat:

• serviceAccountRef diprioritaskan dibanding plaintext serviceAccount.
• Nilai plaintext diabaikan saat ref saudara disetel.

# Pemicu aktivasi

Aktivasi rahasia berjalan pada:

• Startup (preflight plus aktivasi final)
• Jalur hot-apply muat ulang konfigurasi
• Jalur pemeriksaan restart muat ulang konfigurasi
• Muat ulang manual melalui secrets.reload
• Preflight RPC penulisan konfigurasi Gateway (config.set / config.apply / config.patch) untuk keterpecahan SecretRef permukaan aktif di dalam payload konfigurasi yang dikirimkan sebelum menyimpan edit

Kontrak aktivasi:

• Keberhasilan menukar snapshot secara atomik.
• Kegagalan startup membatalkan startup gateway.
• Kegagalan muat ulang runtime mempertahankan snapshot terakhir yang diketahui baik.
• Kegagalan preflight write-RPC menolak konfigurasi yang dikirimkan dan menjaga konfigurasi disk serta snapshot runtime aktif tetap tidak berubah.
• Memberikan token channel per-panggilan eksplisit ke panggilan helper/tool keluar tidak memicu aktivasi SecretRef; titik aktivasi tetap startup, muat ulang, dan secrets.reload eksplisit.

# Sinyal terdegradasi dan pulih

Saat aktivasi pada waktu muat ulang gagal setelah status sehat, OpenClaw memasuki status rahasia terdegradasi.

Kode log dan peristiwa sistem sekali jalan:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Perilaku:

• Terdegradasi: runtime mempertahankan snapshot terakhir yang diketahui baik.
• Pulih: dipancarkan sekali setelah aktivasi berhasil berikutnya.
• Kegagalan berulang saat sudah terdegradasi mencatat peringatan tetapi tidak membanjiri peristiwa.
• Fail-fast startup tidak memancarkan peristiwa terdegradasi karena runtime tidak pernah menjadi aktif.

# Resolusi jalur perintah

Jalur perintah dapat ikut memakai resolusi SecretRef yang didukung melalui RPC snapshot gateway.

Ada dua perilaku umum:

Catatan lain:

• Refresh snapshot setelah rotasi rahasia backend ditangani oleh openclaw secrets reload.
• Metode RPC Gateway yang digunakan oleh jalur perintah ini: secrets.resolve.

# Alur kerja audit dan konfigurasi

Alur operator default:

openclaw secrets audit --check

openclaw secrets configure

openclaw secrets audit --check

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

# Kebijakan keselamatan satu arah

Model keselamatan:

• preflight harus berhasil sebelum mode tulis
• aktivasi runtime divalidasi sebelum commit
• penerapan memperbarui file menggunakan penggantian file atomik dan pemulihan best-effort saat gagal

# Catatan kompatibilitas auth legacy

Untuk kredensial statis, runtime tidak lagi bergantung pada penyimpanan auth legacy plaintext.

• Sumber kredensial runtime adalah snapshot dalam memori yang terselesaikan.
• Entri api_key statis legacy dihapus saat ditemukan.
• Perilaku kompatibilitas terkait OAuth tetap terpisah.

# Catatan UI Web

Beberapa union SecretInput lebih mudah dikonfigurasi dalam mode editor mentah daripada dalam mode formulir.

# Terkait

• Autentikasi — penyiapan autentikasi
• CLI: secrets — perintah CLI
• Variabel Lingkungan — prioritas lingkungan
• Permukaan Kredensial SecretRef — permukaan kredensial
• Kontrak Rencana Penerapan Secrets — detail kontrak rencana
• Keamanan — postur keamanan