Zarządzanie sekretami

OpenClaw obsługuje addytywne SecretRefs, dzięki czemu obsługiwane dane uwierzytelniające nie muszą być przechowywane w konfiguracji jako zwykły tekst.

Model środowiska uruchomieniowego

• Sekrety są rozwiązywane do migawki środowiska uruchomieniowego przechowywanej w pamięci — z wyprzedzeniem podczas aktywacji, a nie leniwie w ścieżkach żądań.
• Uruchamianie natychmiast kończy się niepowodzeniem, gdy nie można rozwiązać faktycznie aktywnego SecretRef.
• Ponowne wczytanie jest atomową zamianą: pełny sukces albo zachowanie ostatniej poprawnej migawki.
• Naruszenia zasad (na przykład profil uwierzytelniania w trybie OAuth połączony z danymi wejściowymi SecretRef) powodują niepowodzenie aktywacji przed zamianą migawki środowiska uruchomieniowego.
• Żądania środowiska uruchomieniowego odczytują wyłącznie aktywną migawkę w pamięci. Dane uwierzytelniające SecretRef dostawców modeli przechodzą przez magazyn uwierzytelniania i opcje strumienia jako lokalne dla procesu wartości zastępcze aż do wysłania. Ścieżki dostarczania wychodzącego (dostarczanie odpowiedzi i wątków w Discordzie oraz wysyłanie działań w Telegramie) również odczytują tę migawkę i nie rozwiązują ponownie odwołań przy każdym wysłaniu.

Dzięki temu awarie dostawców sekretów nie wpływają na intensywnie używane ścieżki żądań.

Wstrzykiwanie podczas wysyłania (wartości zastępcze)

W przypadku danych uwierzytelniających dostawców modeli opartych na SecretRefs OpenClaw tworzy nieprzejrzystą, lokalną dla procesu wartość zastępczą podczas rozwiązywania uwierzytelniania modelu. Magazyn uwierzytelniania, opcje strumienia, konfiguracja SDK, dzienniki, obiekty błędów i większość mechanizmów introspekcji środowiska uruchomieniowego widzą więc wartość taką jak oc-sent-v1-..., a nie dane uwierzytelniające dostawcy. Chronione pobieranie modelu i zarządzane sondy kondycji lokalnego dostawcy zastępują znane wartości zastępcze w adresach URL i wartościach nagłówków bezpośrednio przed opuszczeniem procesu przez każde żądanie.

Nieznane wartości o formacie wartości zastępczej powodują bezpieczne przerwanie działania przed rozpoczęciem aktywności sieciowej. OpenClaw odmawia wysłania żądania zamiast przekazać dostawcy nierozwiązaną wartość zastępczą. Rozwiązane wartości sekretów są również rejestrowane na potrzeby redagowania ich dokładnych wartości w dziennikach jako dodatkowy mechanizm ochronny.

Adaptery dostawców korzystają z najpóźniejszego punktu wstrzykiwania obsługiwanego przez ich SDK:

• SDK z opcją niestandardowego pobierania otrzymują chronioną funkcję pobierania OpenClaw, dzięki czemu SDK zachowuje wartość zastępczą.
• SDK bez opcji niestandardowego pobierania odpakowują wartość zastępczą bezpośrednio przed utworzeniem klienta. Strumienie dostawców należące do pluginów i uprzęże agentów odpakowują ją w ostatnim punkcie przekazania należącym do rdzenia, ponieważ te transporty nie współdzielą chronionej funkcji pobierania OpenClaw.

Wartości zastępcze ograniczają ekspozycję zwykłego tekstu w całym łańcuchu wywołania modelu, ale nie zapewniają izolacji procesu. Rzeczywista wartość nadal istnieje w pamięci tego samego procesu i pojawia się na końcowej granicy adaptera. Dane uwierzytelniające w postaci zwykłego tekstu ze zmiennych środowiskowych, które nie są skonfigurowane za pomocą SecretRefs, pozostają zwykłym tekstem i nie są objęte tym mechanizmem.

Ustaw OPENCLAW_SECRET_SENTINELS=off (akceptowane są również 0 lub false, bez rozróżniania wielkości liter), aby wyłączyć tworzenie wartości zastępczych podczas reagowania na incydenty lub rozwiązywania problemów ze zgodnością. Wyłącznik awaryjny nie wyłącza rejestrowania dokładnych wartości na potrzeby redagowania.

Granica dostępu agenta

SecretRefs zapobiegają utrwalaniu danych uwierzytelniających w konfiguracji i wygenerowanych plikach modeli, ale nie stanowią granicy izolacji procesu. Dane uwierzytelniające w postaci zwykłego tekstu pozostawione na dysku w ścieżce, którą agent może odczytać, nadal można odczytać za pomocą narzędzi plikowych lub powłoki, z pominięciem redagowania na poziomie API.

W przypadku wdrożeń produkcyjnych, w których uwzględnia się pliki dostępne dla agenta, migrację należy uznać za zakończoną tylko wtedy, gdy spełnione są wszystkie poniższe warunki:

• Obsługiwane dane uwierzytelniające używają SecretRefs zamiast wartości w postaci zwykłego tekstu.
• Pozostałości starszych danych w postaci zwykłego tekstu zostały usunięte z openclaw.json, auth-profiles.json, .env i wygenerowanych plików models.json.
• openclaw secrets audit --check nie wykazuje problemów po migracji.
• Wszelkie pozostałe nieobsługiwane lub rotowane dane uwierzytelniające są chronione przez izolację systemu operacyjnego, izolację kontenera albo zewnętrzny serwer proxy danych uwierzytelniających.

Dlatego przepływ audytu, konfiguracji i zastosowania stanowi zabezpieczenie migracji, a nie tylko wygodne narzędzie pomocnicze.

Filtrowanie aktywnych powierzchni

SecretRefs są weryfikowane tylko na faktycznie aktywnych powierzchniach:

• Włączone powierzchnie: nierozwiązane odwołania blokują uruchamianie lub ponowne wczytanie.
• Nieaktywne powierzchnie: nierozwiązane odwołania nie blokują uruchamiania ani ponownego wczytania; generują niekrytyczny komunikat diagnostyczny SECRETS_REF_IGNORED_INACTIVE_SURFACE.

Diagnostyka powierzchni uwierzytelniania Gateway

Gdy SecretRef jest ustawione w gateway.auth.token, gateway.auth.password, gateway.remote.token lub gateway.remote.password, uruchamianie lub ponowne wczytanie Gateway zapisuje stan powierzchni w dzienniku pod kodem SECRETS_GATEWAY_AUTH_SURFACE:

• active: SecretRef jest częścią faktycznie używanej powierzchni uwierzytelniania i musi zostać rozwiązane.
• inactive: pierwszeństwo ma inna powierzchnia uwierzytelniania albo uwierzytelnianie zdalne jest wyłączone lub nieaktywne.

Wpis dziennika zawiera przyczynę zastosowania zasad aktywnej powierzchni.

Wstępna kontrola odwołań podczas wdrażania

Podczas interaktywnego wdrażania wybranie przechowywania SecretRef powoduje przeprowadzenie wstępnej weryfikacji przed zapisaniem:

• Odwołania do zmiennych środowiskowych: weryfikują nazwę zmiennej środowiskowej i potwierdzają, że podczas konfiguracji widoczna jest niepusta wartość.
• Odwołania do dostawców (file lub exec): weryfikują wybór dostawcy, rozwiązują id i sprawdzają typ rozwiązanej wartości.
• Przepływ szybkiego startu: gdy gateway.auth.token jest już SecretRef, wdrażanie rozwiązuje je przed sondą lub inicjalizacją pulpitu (dla odwołań env, file i exec), używając tego samego mechanizmu natychmiastowego przerwania w razie niepowodzenia.

Niepowodzenie weryfikacji powoduje wyświetlenie błędu i umożliwia ponowienie próby.

Kontrakt SecretRef

Jeden kształt obiektu we wszystkich miejscach:

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

Konfiguracja dostawcy

Dostawców należy zdefiniować w secrets.providers:

{  secrets: {    providers: {      default: { source: "env" },      filemain: {        source: "file",        path: "~/.openclaw/secrets.json",        mode: "json", // lub "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": { "code": "NOT_FOUND" } }}

Klucze API przechowywane w plikach

Nie umieszczaj ciągów file:... w bloku konfiguracji env. Ten blok ma charakter dosłowny i nie jest nadpisywany, dlatego file:... nigdy nie jest w nim rozwiązywane.

Zamiast tego użyj plikowego SecretRef w obsługiwanym polu danych uwierzytelniających:

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

Dla mode: "singleValue" wartością id odwołania SecretRef jest "value". Dla mode: "json" użyj bezwzględnego wskaźnika JSON, takiego jak "/providers/xai/apiKey".

Pola akceptujące odwołania SecretRef opisano w sekcji Obsługiwane pola danych uwierzytelniających SecretRef.

Przykłady integracji exec

Dedykowany przewodnik po 1Password, obejmujący konta usług, dołączoną umiejętność agenta i rozwiązywanie problemów, znajduje się w sekcji 1Password.

{  secrets: {    providers: {      onepassword_openai: {        source: "exec",        command: "/opt/homebrew/bin/op",        allowSymlinkCommand: true, // wymagane dla plików binarnych Homebrew będących dowiązaniami symbolicznymi        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, // wymagane dla plików binarnych Homebrew będących dowiązaniami symbolicznymi        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(`Nie udało się przeanalizować żądania: ${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 || `polecenie pass zakończyło się ze stanem ${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, // wymagane dla plików binarnych Homebrew będących dowiązaniami symbolicznymi        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" },      },    },  },}

Zmienne środowiskowe serwera MCP

Zmienne środowiskowe serwera MCP skonfigurowane za pomocą plugins.entries.acpx.config.mcpServers akceptują SecretInput, dzięki czemu klucze API i tokeny nie trafiają do konfiguracji w postaci zwykłego tekstu:

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

Wartości ciągów w postaci zwykłego tekstu nadal działają. Odwołania szablonów środowiskowych, takie jak ${MCP_SERVER_API_KEY}, oraz obiekty SecretRef są rozwiązywane podczas aktywacji Gateway, zanim zostanie uruchomiony proces serwera MCP. Tak jak w przypadku innych powierzchni SecretRef, nierozwiązane odwołania blokują aktywację tylko wtedy, gdy plugin acpx jest faktycznie aktywny.

Materiały uwierzytelniające SSH piaskownicy

Podstawowy backend piaskownicy ssh obsługuje również odwołania SecretRef dla materiałów uwierzytelniających 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" },        },      },    },  },}

Zachowanie w czasie działania:

• OpenClaw rozwiązuje te odwołania podczas aktywacji piaskownicy, a nie leniwie przy każdym wywołaniu SSH.
• Rozwiązane wartości są zapisywane w katalogu tymczasowym z restrykcyjnymi uprawnieniami do plików (0o600) i używane w wygenerowanej konfiguracji SSH.
• Jeśli efektywnym backendem piaskownicy nie jest ssh (lub trybem piaskownicy jest off), te odwołania pozostają nieaktywne i nie blokują uruchamiania.

Obsługiwany zakres poświadczeń

Kanoniczna lista obsługiwanych i nieobsługiwanych poświadczeń znajduje się w dokumencie Zakres poświadczeń SecretRef.

Wymagane zachowanie i pierwszeństwo

• Pole bez odwołania: bez zmian.
• Pole z odwołaniem: wymagane na aktywnych powierzchniach podczas aktywacji.
• Jeśli obecne są zarówno zwykły tekst, jak i odwołanie, odwołanie ma pierwszeństwo na obsługiwanych ścieżkach pierwszeństwa.
• Znacznik redakcji __OPENCLAW_REDACTED__ jest zarezerwowany do wewnętrznej redakcji i przywracania konfiguracji, a jego dosłowne użycie w przesłanych danych konfiguracyjnych jest odrzucane.

Sygnały ostrzegawcze i audytowe:

• SECRETS_REF_OVERRIDES_PLAINTEXT (ostrzeżenie w czasie działania)
• REF_SHADOWED (ustalenie audytu, gdy poświadczenia auth-profiles.json mają pierwszeństwo przed odwołaniami openclaw.json)

Zgodność z Google Chat: serviceAccountRef ma pierwszeństwo przed wartością zwykłego tekstu serviceAccount; po ustawieniu sąsiedniego odwołania wartość zwykłego tekstu jest ignorowana.

Wyzwalacze aktywacji

Aktywacja sekretów jest uruchamiana podczas:

• Uruchamiania (kontrola wstępna i końcowa aktywacja)
• Ścieżki natychmiastowego zastosowania po ponownym wczytaniu konfiguracji
• Ścieżki sprawdzania konieczności ponownego uruchomienia po ponownym wczytaniu konfiguracji
• Ręcznego ponownego wczytania za pomocą secrets.reload
• Kontroli wstępnej RPC zapisu konfiguracji Gateway (config.set / config.apply / config.patch), sprawdzającej możliwość rozwiązania SecretRef na aktywnych powierzchniach w przesłanym ładunku konfiguracji przed utrwaleniem zmian

Kontrakt aktywacji:

• Powodzenie atomowo podmienia migawkę.
• Błąd podczas uruchamiania przerywa uruchamianie Gateway.
• Błąd ponownego wczytania w czasie działania zachowuje ostatnią prawidłową migawkę.
• Błąd kontroli wstępnej RPC zapisu odrzuca przesłaną konfigurację; zarówno konfiguracja na dysku, jak i aktywna migawka środowiska wykonawczego pozostają bez zmian.
• Przekazanie jawnego tokenu kanału dla pojedynczego wywołania do wychodzącego pomocnika lub wywołania narzędzia nie uruchamia aktywacji SecretRef; punktami aktywacji pozostają uruchamianie, ponowne wczytanie i jawne secrets.reload.

Sygnały degradacji i odzyskania

Gdy aktywacja podczas ponownego wczytania zakończy się niepowodzeniem po osiągnięciu prawidłowego stanu, OpenClaw przechodzi w zdegradowany stan sekretów, emitując jednorazowe zdarzenia systemowe i kody dziennika:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Zachowanie:

• Degradacja: środowisko wykonawcze zachowuje ostatnią prawidłową migawkę.
• Odzyskanie: emitowane raz po kolejnej udanej aktywacji.
• Powtarzające się błędy w już zdegradowanym stanie zapisują ostrzeżenia w dzienniku, ale nie emitują ponownie zdarzenia.
• Szybkie przerwanie podczas uruchamiania nigdy nie emituje zdarzenia degradacji, ponieważ środowisko wykonawcze nie stało się aktywne.

Rozwiązywanie ścieżek poleceń

Ścieżki poleceń mogą włączyć obsługiwane rozwiązywanie SecretRef za pośrednictwem RPC migawki Gateway. Obowiązują dwa ogólne zachowania:

Pozostałe uwagi:

• Odświeżanie migawki po rotacji sekretu backendu jest obsługiwane przez openclaw secrets reload.
• Metoda RPC Gateway używana przez te ścieżki poleceń: secrets.resolve.

Przepływ audytu i konfiguracji

Domyślny przepływ operatora:

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

Nie należy uznawać migracji za zakończoną, dopóki ponowny audyt nie wykaże braku problemów. Jeśli audyt nadal zgłasza przechowywane wartości zwykłego tekstu, ryzyko dostępu agenta pozostaje, nawet gdy interfejsy API środowiska wykonawczego zwracają zredagowane wartości.

Jeśli podczas configure plan zostanie zapisany zamiast zastosowany, przed ponownym audytem należy zastosować zapisany plan za pomocą openclaw secrets apply --from <plan-path>.

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

Jednokierunkowa polityka bezpieczeństwa

Model bezpieczeństwa:

• Kontrola wstępna musi zakończyć się powodzeniem przed przejściem do trybu zapisu.
• Aktywacja środowiska wykonawczego jest weryfikowana przed zatwierdzeniem.
• Operacja zastosowania aktualizuje pliki za pomocą atomowej zamiany plików i podejmuje możliwie najlepszą próbę przywrócenia po błędzie.

Uwagi dotyczące zgodności ze starszym uwierzytelnianiem

W przypadku statycznych poświadczeń środowisko wykonawcze nie zależy już od starszego magazynu uwierzytelniania w postaci zwykłego tekstu.

• Źródłem poświadczeń środowiska wykonawczego jest rozwiązana migawka w pamięci.
• Starsze statyczne wpisy api_key są usuwane po wykryciu.
• Zachowanie zgodności związane z OAuth pozostaje odrębne.

Uwaga dotycząca interfejsu WWW

Niektóre unie SecretInput łatwiej skonfigurować w trybie edytora surowego niż w trybie formularza.

Powiązane

• Uwierzytelnianie - konfiguracja uwierzytelniania
• CLI: sekrety - polecenia CLI
• SecretRef magazynu Vault - konfiguracja dostawcy HashiCorp Vault
• Zmienne środowiskowe - pierwszeństwo zmiennych środowiskowych
• Zakres poświadczeń SecretRef - zakres poświadczeń
• Kontrakt planu stosowania sekretów - szczegóły kontraktu planu
• Bezpieczeństwo - podejście do bezpieczeństwa