Gizli bilgilerin yönetimi

OpenClaw, desteklenen kimlik bilgilerinin yapılandırmada düz metin olarak saklanmasına gerek kalmaması için eklemeli SecretRefs'i destekler.

Hedefler ve çalışma zamanı modeli

Secret'lar, bellek içi bir çalışma zamanı anlık görüntüsüne çözümlenir.

• Çözümleme, istek yollarında tembel değil, etkinleştirme sırasında isteklidir.
• Etkin olarak aktif bir SecretRef çözümlenemediğinde başlatma hızlı başarısız olur.
• Yeniden yükleme atomik takas kullanır: tam başarı ya da bilinen son iyi anlık görüntüyü koru.
• SecretRef ilke ihlalleri (örneğin SecretRef girdisiyle birleştirilmiş OAuth modunda auth profilleri) çalışma zamanı takasından önce etkinleştirmeyi başarısız kılar.
• Çalışma zamanı istekleri yalnızca aktif bellek içi anlık görüntüden okur.
• İlk başarılı yapılandırma etkinleştirmesi/yüklemesinden sonra, çalışma zamanı kod yolları başarılı bir yeniden yükleme onu değiştirene kadar bu aktif bellek içi anlık görüntüyü okumayı sürdürür.
• Giden teslim yolları da bu aktif anlık görüntüden okur (örneğin Discord yanıt/iş parçacığı teslimi ve Telegram eylem gönderimleri); her gönderimde SecretRefs'i yeniden çözümlemezler.

Bu, secret sağlayıcı kesintilerini sıcak istek yollarının dışında tutar.

Agent erişim sınırı

SecretRefs, kimlik bilgilerini desteklenen yapılandırma ve oluşturulmuş model yüzeylerinde kalıcı hale getirilmekten korur, ancak bir süreç yalıtımı sınırı değildir. Bir düz metin kimlik bilgisi, agent'ın okuyabildiği bir yolda diskte kalırsa agent, dosya veya kabuk araçlarını kullanarak o dosyayı inceleyip API düzeyi redaksiyonu atlayabilir.

Agent tarafından erişilebilir dosyaların kapsamda olduğu üretim dağıtımları için, SecretRef geçişini yalnızca şunların tümü doğru olduğunda tamamlanmış kabul edin:

• desteklenen kimlik bilgileri düz metin değerler yerine SecretRefs kullanır
• eski düz metin kalıntıları openclaw.json, auth-profiles.json, .env ve oluşturulmuş models.json dosyalarından temizlenmiştir
• geçişten sonra openclaw secrets audit --check temizdir
• kalan desteklenmeyen veya dönen kimlik bilgileri işletim sistemi yalıtımı, container yalıtımı veya harici bir kimlik bilgisi proxy'si tarafından korunur

Bu nedenle audit/configure/apply iş akışı yalnızca kolaylık sağlayan bir yardımcı değil, bir güvenlik geçiş kapısıdır.

Aktif yüzey filtreleme

SecretRefs yalnızca etkin olarak aktif yüzeylerde doğrulanır.

• Etkin yüzeyler: çözümlenmemiş refs başlatmayı/yeniden yüklemeyi engeller.
• Aktif olmayan yüzeyler: çözümlenmemiş refs başlatmayı/yeniden yüklemeyi engellemez.
• Aktif olmayan refs, SECRETS_REF_IGNORED_INACTIVE_SURFACE koduyla ölümcül olmayan tanılamalar üretir.

Gateway auth yüzeyi tanılamaları

gateway.auth.token, gateway.auth.password, gateway.remote.token veya gateway.remote.password üzerinde bir SecretRef yapılandırıldığında, Gateway başlatma/yeniden yükleme yüzey durumunu açıkça günlüğe yazar:

• active: SecretRef, etkin auth yüzeyinin parçasıdır ve çözümlenmelidir.
• inactive: Başka bir auth yüzeyi kazandığı için veya uzak auth devre dışı/aktif olmadığı için SecretRef bu çalışma zamanı için yok sayılır.

Bu girdiler SECRETS_GATEWAY_AUTH_SURFACE ile günlüğe yazılır ve aktif yüzey ilkesi tarafından kullanılan nedeni içerir; böylece bir kimlik bilgisinin neden aktif veya aktif olmayan olarak ele alındığını görebilirsiniz.

İlk kurulum referans ön kontrolü

İlk kurulum etkileşimli modda çalıştığında ve SecretRef depolamasını seçtiğinizde OpenClaw, kaydetmeden önce ön kontrol doğrulaması çalıştırır:

• Env refs: env var adını doğrular ve kurulum sırasında boş olmayan bir değerin görünür olduğunu onaylar.
• Sağlayıcı refs (file veya exec): sağlayıcı seçimini doğrular, id değerini çözümler ve çözümlenen değer türünü denetler.
• Quickstart yeniden kullanım yolu: gateway.auth.token zaten bir SecretRef olduğunda, ilk kurulum probe/dashboard bootstrap öncesinde (env, file ve exec refs için) aynı hızlı başarısız kapıyı kullanarak onu çözümler.

Doğrulama başarısız olursa ilk kurulum hatayı gösterir ve yeniden denemenize izin verir.

SecretRef sözleşmesi

Her yerde tek bir nesne şekli kullanın:

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

Sağlayıcı yapılandırması

Sağlayıcıları secrets.providers altında tanımlayın:

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

Dosya destekli API anahtarları

Yapılandırma env bloğuna file:... string'leri koymayın. env bloğu literal ve geçersiz kılmayan yapıdadır, bu nedenle file:... çözümlenmez.

Bunun yerine desteklenen bir kimlik bilgisi alanında dosya SecretRef kullanın:

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

mode: "singleValue" için SecretRef id, "value" değeridir. mode: "json" için "/providers/xai/apiKey" gibi mutlak bir JSON pointer kullanın.

SecretRefs kabul eden yapılandırma alanları için SecretRef kimlik bilgisi yüzeyi bölümüne bakın.

Exec entegrasyon örnekleri

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

MCP sunucusu ortam değişkenleri

plugins.entries.acpx.config.mcpServers üzerinden yapılandırılan MCP sunucusu env var'ları SecretInput destekler. Bu, API anahtarlarını ve token'ları düz metin yapılandırmasının dışında tutar:

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

Düz metin string değerler çalışmaya devam eder. ${MCP_SERVER_API_KEY} gibi env-template refs ve SecretRef nesneleri, MCP sunucusu işlemi başlatılmadan önce Gateway etkinleştirmesi sırasında çözümlenir. Diğer SecretRef yüzeylerinde olduğu gibi, çözümlenemeyen refs yalnızca acpx Plugin'i fiilen etkin olduğunda etkinleştirmeyi engeller.

Sandbox SSH kimlik doğrulama materyali

Çekirdek ssh sandbox backend'i, SSH kimlik doğrulama materyali için SecretRefs desteği de sunar:

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

Çalışma zamanı davranışı:

• OpenClaw bu refs değerlerini her SSH çağrısında tembel olarak değil, sandbox etkinleştirmesi sırasında çözer.
• Çözümlenen değerler kısıtlayıcı izinlerle geçici dosyalara yazılır ve oluşturulan SSH yapılandırmasında kullanılır.
• Etkin sandbox backend'i ssh değilse bu refs etkin olmayan durumda kalır ve başlangıcı engellemez.

Desteklenen kimlik bilgisi yüzeyi

Standart desteklenen ve desteklenmeyen kimlik bilgileri şurada listelenir:

• SecretRef Kimlik Bilgisi Yüzeyi

Gerekli davranış ve öncelik

• Ref olmayan alan: değişmez.
• Ref olan alan: etkin yüzeylerde etkinleştirme sırasında zorunludur.
• Hem düz metin hem de ref varsa, desteklenen öncelik yollarında ref önceliklidir.
• Redaction sentinel __OPENCLAW_REDACTED__, dahili yapılandırma redaction/restore için ayrılmıştır ve literal olarak gönderilen yapılandırma verisi olarak reddedilir.

Uyarı ve denetim sinyalleri:

• SECRETS_REF_OVERRIDES_PLAINTEXT (çalışma zamanı uyarısı)
• REF_SHADOWED (auth-profiles.json kimlik bilgilerinin openclaw.json refs değerlerine göre öncelik aldığı denetim bulgusu)

Google Chat uyumluluk davranışı:

• serviceAccountRef, düz metin serviceAccount değerine göre önceliklidir.
• Kardeş ref ayarlandığında düz metin değer yok sayılır.

Etkinleştirme tetikleyicileri

Secret etkinleştirmesi şu durumlarda çalışır:

• Başlangıç (preflight artı son etkinleştirme)
• Yapılandırma yeniden yükleme hot-apply yolu
• Yapılandırma yeniden yükleme restart-check yolu
• secrets.reload üzerinden manuel yeniden yükleme
• Düzenlemeleri kalıcılaştırmadan önce gönderilen yapılandırma payload'u içinde etkin yüzey SecretRef çözümlenebilirliği için Gateway yapılandırma yazma RPC preflight'ı (config.set / config.apply / config.patch)

Etkinleştirme sözleşmesi:

• Başarı snapshot'ı atomik olarak değiştirir.
• Başlangıç hatası Gateway başlangıcını iptal eder.
• Çalışma zamanı yeniden yükleme hatası bilinen son iyi snapshot'ı korur.
• Yazma RPC preflight hatası gönderilen yapılandırmayı reddeder ve hem disk yapılandırmasını hem de etkin çalışma zamanı snapshot'ını değiştirmeden korur.
• Bir outbound helper/tool çağrısına açık bir çağrı başına kanal token'ı sağlamak SecretRef etkinleştirmesini tetiklemez; etkinleştirme noktaları başlangıç, yeniden yükleme ve açık secrets.reload olarak kalır.

Bozulmuş ve kurtarılmış sinyaller

Sağlıklı bir durumdan sonra yeniden yükleme zamanı etkinleştirmesi başarısız olduğunda OpenClaw bozulmuş secrets durumuna girer.

Tek seferlik sistem olayı ve günlük kodları:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Davranış:

• Bozulmuş: çalışma zamanı bilinen son iyi snapshot'ı korur.
• Kurtarılmış: bir sonraki başarılı etkinleştirmeden sonra bir kez yayınlanır.
• Zaten bozulmuş durumdayken tekrarlanan hatalar uyarıları günlüğe yazar ancak olayları tekrarlamaz.
• Başlangıç fail-fast, çalışma zamanı hiç etkinleşmediği için bozulmuş olayları yayınlamaz.

Komut yolu çözümlemesi

Komut yolları, Gateway snapshot RPC üzerinden desteklenen SecretRef çözümlemesine katılmayı seçebilir.

İki genel davranış vardır:

Diğer notlar:

• Arka uç gizli bilgi döndürmesinden sonra anlık görüntü yenilemesi openclaw secrets reload tarafından işlenir.
• Bu komut yolları tarafından kullanılan Gateway RPC yöntemi: secrets.resolve.

Denetim ve yapılandırma iş akışı

Varsayılan operatör akışı:

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

Yeniden denetim temiz çıkana kadar geçişi tamamlanmış saymayın. Denetim durağan halde hâlâ düz metin değerler bildiriyorsa, çalışma zamanı API’leri redakte edilmiş değerler döndürse bile ajan erişimi riski hâlâ mevcuttur.

configure sırasında uygulamak yerine bir plan kaydederseniz, yeniden denetimden önce bu kaydedilmiş planı openclaw secrets apply --from <plan-path> ile uygulayın.

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

Tek yönlü güvenlik ilkesi

Güvenlik modeli:

• yazma modundan önce ön kontrol başarılı olmalıdır
• çalışma zamanı etkinleştirmesi commit öncesinde doğrulanır
• uygulama, dosyaları atomik dosya değiştirme ve hata durumunda en iyi çabayla geri yükleme kullanarak günceller

Eski auth uyumluluk notları

Statik kimlik bilgileri için çalışma zamanı artık düz metin eski auth depolamasına bağlı değildir.

• Çalışma zamanı kimlik bilgisi kaynağı, çözümlenmiş bellek içi anlık görüntüdür.
• Eski statik api_key girdileri keşfedildiğinde temizlenir.
• OAuth ile ilgili uyumluluk davranışı ayrı kalır.

Web UI notu

Bazı SecretInput union’larını ham düzenleyici modunda yapılandırmak, form moduna göre daha kolaydır.

İlgili

• Kimlik Doğrulama — auth kurulumu
• CLI: secrets — CLI komutları
• Ortam Değişkenleri — ortam önceliği
• SecretRef Kimlik Bilgisi Yüzeyi — kimlik bilgisi yüzeyi
• Gizli Bilgileri Uygulama Planı Sözleşmesi — plan sözleşmesi ayrıntıları
• Güvenlik — güvenlik duruşu