Manajemen rahasia

OpenClaw mendukung SecretRefs aditif sehingga kredensial yang didukung tidak perlu disimpan sebagai teks biasa dalam konfigurasi.

Tujuan dan model runtime

Rahasia diselesaikan menjadi snapshot runtime dalam memori.

• Resolusi dilakukan secara eager selama aktivasi, bukan lazy pada jalur permintaan.
• Startup gagal cepat ketika SecretRef yang efektif aktif tidak dapat diselesaikan.
• Reload menggunakan pertukaran atomik: sukses penuh, atau pertahankan snapshot terakhir yang diketahui baik.
• Pelanggaran kebijakan SecretRef (misalnya profil auth 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 tersebut tidak menyelesaikan ulang SecretRefs pada setiap pengiriman.

Ini menjauhkan gangguan penyedia rahasia dari jalur permintaan kritis.

Batas akses agen

SecretRefs melindungi kredensial agar tidak dipersistenkan dalam konfigurasi yang didukung dan permukaan model yang dihasilkan, tetapi SecretRefs bukan batas isolasi proses. Jika kredensial teks biasa tetap ada di disk pada jalur yang dapat dibaca agen, agen dapat melewati redaksi tingkat API dengan menggunakan alat file atau shell untuk memeriksa file tersebut.

Untuk deployment produksi ketika file yang dapat diakses agen termasuk dalam cakupan, anggap migrasi SecretRef selesai hanya ketika semua hal berikut benar:

• kredensial yang didukung menggunakan SecretRefs alih-alih nilai teks biasa
• sisa teks biasa legacy telah dibersihkan dari openclaw.json, auth-profiles.json, .env, dan file models.json yang dihasilkan
• openclaw secrets audit --check bersih setelah migrasi
• kredensial lain yang tidak didukung atau berotasi dilindungi oleh isolasi sistem operasi, isolasi kontainer, atau proxy kredensial eksternal

Inilah alasan workflow audit/configure/apply menjadi gerbang migrasi keamanan, bukan sekadar helper praktis.

Pemfilteran permukaan aktif

SecretRefs divalidasi hanya pada permukaan yang efektif aktif.

• Permukaan yang diaktifkan: ref yang belum terselesaikan memblokir startup/reload.
• Permukaan tidak aktif: ref yang belum terselesaikan tidak memblokir startup/reload.
• Ref tidak aktif menghasilkan diagnostik non-fatal dengan kode SECRETS_REF_IGNORED_INACTIVE_SURFACE.

Diagnostik permukaan auth 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 auth efektif dan harus terselesaikan.
• inactive: SecretRef diabaikan untuk runtime ini karena permukaan auth lain menang, atau karena auth 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:

• Ref env: memvalidasi nama env var dan mengonfirmasi nilai yang tidak kosong terlihat selama setup.
• Ref penyedia (file atau exec): memvalidasi pemilihan penyedia, menyelesaikan id, dan memeriksa tipe nilai yang terselesaikan.
• Jalur penggunaan ulang quickstart: ketika gateway.auth.token sudah berupa SecretRef, onboarding menyelesaikannya sebelum bootstrap probe/dashboard (untuk ref 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 semua tempat:

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

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

"${OPENAI_API_KEY}""$OPENAI_API_KEY"

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

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

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,      },      "team-secrets": {        source: "exec",        pluginIntegration: {          pluginId: "acme-secrets",          integrationId: "secret-store",        },      },    },    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" } }}

Kunci API berbasis file

Jangan letakkan string file:... dalam blok env konfigurasi. Blok env bersifat literal dan tidak menimpa, jadi file:... tidak diselesaikan.

Gunakan SecretRef file pada field kredensial yang didukung sebagai gantinya:

{  secrets: {    providers: {      xai_key_file: {        source: "file",        path: "~/.openclaw/secrets/xai-api-key.txt",        mode: "singleValue",      },    },  },  models: {    providers: {      xai: {        apiKey: { source: "file", provider: "xai_key_file", id: "value" },      },    },  },}

Untuk mode: "singleValue", id SecretRef adalah "value". Untuk mode: "json", gunakan pointer JSON absolut seperti "/providers/xai/apiKey".

Lihat Permukaan kredensial SecretRef untuk field konfigurasi yang menerima SecretRefs.

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: {      bws: {        source: "exec",        command: "/usr/local/bin/openclaw-bws-resolver.mjs",        passEnv: ["BWS_ACCESS_TOKEN", "BWS_SERVER_URL", "PATH", "BWS_BIN"],        jsonOnly: true,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: {          source: "exec",          provider: "bws",          id: "openclaw/providers/openai/apiKey",        },      },    },  },}

openclaw secrets audit --allow-exec

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

#!/usr/bin/env nodeconst { spawnSync } = require("node:child_process"); let stdin = "";process.stdin.setEncoding("utf8");process.stdin.on("data", (chunk) => {  stdin += chunk;});process.stdin.on("error", (err) => {  process.stderr.write(`${err.message}\n`);  process.exit(1);});process.stdin.on("end", () => {  let request;  try {    request = JSON.parse(stdin || "{}");  } catch (err) {    process.stderr.write(`Failed to parse request: ${err.message}\n`);    process.exit(1);  }   const passBin = process.env.PASS_BIN || "pass";  const values = {};  const errors = {};   for (const id of request.ids ?? []) {    const result = spawnSync(passBin, ["show", id], { encoding: "utf8" });    if (result.status === 0) {      values[id] = result.stdout.split(/\r?\n/, 1)[0] ?? "";    } else {      errors[id] = { message: (result.stderr || `pass exited ${result.status}`).trim() };    }  }   process.stdout.write(JSON.stringify({ protocolVersion: 1, values, errors }));});

{  secrets: {    providers: {      pass_store: {        source: "exec",        command: "/usr/local/bin/openclaw-pass-resolver",        passEnv: ["PATH", "HOME", "GNUPGHOME", "GPG_TTY", "PASSWORD_STORE_DIR", "PASS_BIN"],        jsonOnly: true,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: {          source: "exec",          provider: "pass_store",          id: "openclaw/providers/openai/apiKey",        },      },    },  },}

openclaw secrets audit --checkopenclaw secrets audit --allow-exec

{  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

Env var server MCP yang dikonfigurasi melalui plugins.entries.acpx.config.mcpServers mendukung SecretInput. Ini menjaga kunci API dan token tetap berada di luar config plaintext:

{  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 plaintext tetap berfungsi. Ref template env seperti ${MCP_SERVER_API_KEY} dan objek SecretRef diselesaikan selama aktivasi gateway sebelum proses server MCP dibuat. Seperti permukaan SecretRef lainnya, ref yang belum terselesaikan hanya memblokir aktivasi saat plugin acpx secara efektif aktif.

Materi auth SSH sandbox

Backend sandbox inti ssh juga mendukung SecretRefs untuk materi auth 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 selama setiap panggilan SSH.
• Nilai yang diselesaikan ditulis ke file temp dengan izin terbatas dan digunakan dalam config 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 dan presedensi yang diperlukan

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

Sinyal peringatan dan audit:

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

Perilaku kompatibilitas Google Chat:

• serviceAccountRef diprioritaskan atas serviceAccount plaintext.
• Nilai plaintext diabaikan saat ref saudara diatur.

Pemicu aktivasi

Aktivasi rahasia berjalan saat:

• Startup (preflight ditambah aktivasi final)
• Jalur hot-apply reload config
• Jalur restart-check reload config
• Reload manual melalui secrets.reload
• Preflight RPC tulis config Gateway (config.set / config.apply / config.patch) untuk resolvabilitas SecretRef permukaan aktif di dalam payload config yang dikirimkan sebelum menyimpan edit

Kontrak aktivasi:

• Berhasil menukar snapshot secara atomik.
• Kegagalan startup membatalkan startup gateway.
• Kegagalan reload runtime mempertahankan snapshot terakhir yang diketahui baik.
• Kegagalan preflight write-RPC menolak config yang dikirimkan dan mempertahankan config disk serta snapshot runtime aktif tanpa perubahan.
• Menyediakan token kanal per panggilan eksplisit ke panggilan helper/tool outbound tidak memicu aktivasi SecretRef; titik aktivasi tetap startup, reload, dan secrets.reload eksplisit.

Sinyal terdegradasi dan pulih

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

Event sistem satu kali dan kode log:

• 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 event.
• Fail-fast startup tidak memancarkan event terdegradasi karena runtime tidak pernah menjadi aktif.

Resolusi jalur perintah

Jalur perintah dapat memilih ikut serta dalam resolusi SecretRef yang didukung melalui RPC snapshot gateway.

Ada dua perilaku umum:

Catatan lain:

• Penyegaran snapshot setelah rotasi secret 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 --apply

openclaw secrets audit --check

Jangan anggap migrasi selesai sampai audit ulang bersih. Jika audit masih melaporkan nilai plaintext saat tersimpan, risiko akses agen masih ada meskipun API runtime mengembalikan nilai yang telah disamarkan.

Jika Anda menyimpan rencana alih-alih menerapkannya selama configure, terapkan rencana tersimpan itu dengan openclaw secrets apply --from <plan-path> sebelum audit ulang.

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

Kebijakan keamanan satu arah

Model keamanan:

• preflight harus berhasil sebelum mode tulis
• aktivasi runtime divalidasi sebelum commit
• apply memperbarui file menggunakan penggantian file atomik dan pemulihan upaya terbaik saat gagal

Catatan kompatibilitas auth legacy

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

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

Catatan Web UI

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

Terkait

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