Zarządzanie sekretami

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

Cele i model runtime

Sekrety są rozwiązywane do przechowywanej w pamięci migawki runtime.

• Rozwiązywanie odbywa się zachłannie podczas aktywacji, a nie leniwie na ścieżkach żądań.
• Uruchamianie kończy się szybko błędem, gdy faktycznie aktywnego SecretRef nie można rozwiązać.
• Ponowne ładowanie używa atomowej podmiany: pełny sukces albo zachowanie ostatniej znanej dobrej migawki.
• Naruszenia zasad SecretRef (na przykład profile uwierzytelniania w trybie OAuth połączone z wejściem SecretRef) przerywają aktywację przed podmianą runtime.
• Żądania runtime czytają wyłącznie z aktywnej migawki w pamięci.
• Po pierwszej udanej aktywacji/wczytaniu konfiguracji ścieżki kodu runtime nadal czytają tę aktywną migawkę w pamięci, dopóki udane ponowne ładowanie jej nie podmieni.
• Ścieżki dostarczania wychodzącego również czytają z tej aktywnej migawki (na przykład dostarczanie odpowiedzi/wątków Discord i wysyłanie akcji Telegram); nie rozwiązują ponownie SecretRefs przy każdym wysłaniu.

Dzięki temu awarie dostawców sekretów pozostają poza gorącymi ścieżkami żądań.

Granica dostępu agenta

SecretRefs chronią poświadczenia przed utrwalaniem w obsługiwanej konfiguracji i wygenerowanych powierzchniach modeli, ale nie są granicą izolacji procesu. Jeśli poświadczenie w zwykłym tekście pozostaje na dysku w ścieżce, którą agent może odczytać, agent może ominąć redakcję na poziomie API, używając narzędzi plikowych lub powłoki do sprawdzenia tego pliku.

W przypadku wdrożeń produkcyjnych, w których pliki dostępne dla agenta są objęte zakresem, traktuj migrację SecretRef jako ukończoną tylko wtedy, gdy spełnione są wszystkie poniższe warunki:

• obsługiwane poświadczenia używają SecretRefs zamiast wartości w zwykłym tekście
• pozostałości starszego zwykłego tekstu zostały usunięte z openclaw.json, auth-profiles.json, .env oraz wygenerowanych plików models.json
• openclaw secrets audit --check jest czysty po migracji
• wszelkie pozostałe nieobsługiwane lub rotowane poświadczenia są chronione przez izolację systemu operacyjnego, izolację kontenera albo zewnętrzny proxy poświadczeń

Dlatego przepływ audit/configure/apply jest bramą migracji bezpieczeństwa, a nie tylko pomocnikiem wygody.

Filtrowanie aktywnych powierzchni

SecretRefs są walidowane tylko na faktycznie aktywnych powierzchniach.

• Włączone powierzchnie: nierozwiązane refs blokują uruchomienie/ponowne ładowanie.
• Nieaktywne powierzchnie: nierozwiązane refs nie blokują uruchomienia/ponownego ładowania.
• Nieaktywne refs emitują niekrytyczne diagnostyki z kodem SECRETS_REF_IGNORED_INACTIVE_SURFACE.

Diagnostyka powierzchni uwierzytelniania Gateway

Gdy SecretRef jest skonfigurowany w gateway.auth.token, gateway.auth.password, gateway.remote.token lub gateway.remote.password, uruchomienie/ponowne ładowanie Gateway jawnie loguje stan powierzchni:

• active: SecretRef jest częścią efektywnej powierzchni uwierzytelniania i musi zostać rozwiązany.
• inactive: SecretRef jest ignorowany dla tego runtime, ponieważ wygrywa inna powierzchnia uwierzytelniania albo zdalne uwierzytelnianie jest wyłączone/nieaktywne.

Te wpisy są logowane z SECRETS_GATEWAY_AUTH_SURFACE i zawierają powód użyty przez zasadę aktywnej powierzchni, dzięki czemu można zobaczyć, dlaczego poświadczenie potraktowano jako aktywne lub nieaktywne.

Preflight odniesienia podczas onboardingu

Gdy onboarding działa w trybie interaktywnym i wybierzesz przechowywanie SecretRef, OpenClaw uruchamia walidację preflight przed zapisaniem:

• Env refs: waliduje nazwę zmiennej env i potwierdza, że podczas konfiguracji widoczna jest niepusta wartość.
• Provider refs (file lub exec): waliduje wybór dostawcy, rozwiązuje id i sprawdza typ rozwiązanej wartości.
• Ścieżka ponownego użycia Quickstart: gdy gateway.auth.token jest już SecretRef, onboarding rozwiązuje go przed bootstrapem probe/dashboard (dla refs env, file i exec) przy użyciu tej samej bramy szybkiego błędu.

Jeśli walidacja się nie powiedzie, onboarding pokazuje błąd i pozwala spróbować ponownie.

Kontrakt SecretRef

Używaj jednego kształtu obiektu wszędzie:

{ 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

Zdefiniuj dostawców w 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" } }}

Klucze API oparte na pliku

Nie umieszczaj ciągów file:... w bloku konfiguracji env. Blok env jest literalny i nienadpisujący, więc file:... nie jest rozwiązywane.

Zamiast tego użyj plikowego SecretRef w obsługiwanym polu poświadczenia:

{  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" id SecretRef to "value". Dla mode: "json" użyj bezwzględnego wskaźnika JSON, takiego jak "/providers/xai/apiKey".

Zobacz Powierzchnia poświadczeń SecretRef, aby poznać pola konfiguracji akceptujące SecretRefs.

Przykłady integracji 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" },      },    },  },}

Zmienne środowiskowe serwera MCP

Zmienne środowiskowe serwera MCP skonfigurowane przez plugins.entries.acpx.config.mcpServers obsługują SecretInput. Dzięki temu 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 tekstowe nadal działają. Odwołania szablonów środowiskowych, takie jak ${MCP_SERVER_API_KEY}, oraz obiekty SecretRef są rozwiązywane podczas aktywacji gateway przed uruchomieniem procesu serwera MCP. Podobnie jak w przypadku innych powierzchni SecretRef, nierozwiązane odwołania blokują aktywację tylko wtedy, gdy plugin acpx jest faktycznie aktywny.

Materiał uwierzytelniający SSH sandboxa

Główny backend sandboxa ssh obsługuje również SecretRefs dla materiału uwierzytelniającego 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 sandboxa, a nie leniwie przy każdym wywołaniu SSH.
• Rozwiązane wartości są zapisywane do plików tymczasowych z restrykcyjnymi uprawnieniami i używane w wygenerowanej konfiguracji SSH.
• Jeśli efektywny backend sandboxa nie jest ssh, te odwołania pozostają nieaktywne i nie blokują uruchamiania.

Obsługiwana powierzchnia poświadczeń

Kanoniczne obsługiwane i nieobsługiwane poświadczenia są wymienione w:

• Powierzchnia 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.
• Sentinel redakcji __OPENCLAW_REDACTED__ jest zarezerwowany dla wewnętrznej redakcji/przywracania konfiguracji i jest odrzucany jako dosłowne przesłane dane konfiguracji.

Sygnały ostrzeżeń i audytu:

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

Zachowanie zgodności Google Chat:

• serviceAccountRef ma pierwszeństwo przed zwykłym tekstem serviceAccount.
• Wartość w postaci zwykłego tekstu jest ignorowana, gdy ustawione jest siostrzane odwołanie.

Wyzwalacze aktywacji

Aktywacja sekretów uruchamia się przy:

• Uruchomieniu (kontrola wstępna oraz końcowa aktywacja)
• Ścieżce gorącego zastosowania przeładowania konfiguracji
• Ścieżce sprawdzenia restartu przy przeładowaniu konfiguracji
• Ręcznym przeładowaniu przez secrets.reload
• Kontroli wstępnej RPC zapisu konfiguracji Gateway (config.set / config.apply / config.patch) pod kątem rozwiązywalności SecretRef na aktywnej powierzchni w przesłanym ładunku konfiguracji przed utrwaleniem edycji

Kontrakt aktywacji:

• Sukces atomowo podmienia migawkę.
• Niepowodzenie uruchamiania przerywa uruchamianie gateway.
• Niepowodzenie przeładowania w czasie działania zachowuje ostatnią znaną dobrą migawkę.
• Niepowodzenie kontroli wstępnej write-RPC odrzuca przesłaną konfigurację i pozostawia zarówno konfigurację na dysku, jak i aktywną migawkę czasu działania bez zmian.
• Podanie jawnego tokenu kanału dla pojedynczego wywołania do wychodzącego pomocnika/narzędzia nie wyzwala aktywacji SecretRef; punktami aktywacji pozostają uruchamianie, przeładowanie i jawne secrets.reload.

Sygnały degradacji i przywrócenia

Gdy aktywacja podczas przeładowania nie powiedzie się po zdrowym stanie, OpenClaw przechodzi w zdegradowany stan sekretów.

Jednorazowe zdarzenie systemowe i kody dziennika:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Zachowanie:

• Zdegradowany: runtime zachowuje ostatnią znaną dobrą migawkę.
• Przywrócony: emitowane raz po następnej udanej aktywacji.
• Powtarzające się niepowodzenia, gdy system jest już zdegradowany, zapisują ostrzeżenia, ale nie zalewają zdarzeniami.
• Szybkie przerwanie uruchamiania nie emituje zdarzeń degradacji, ponieważ runtime nigdy nie stał się aktywny.

Rozwiązywanie ścieżek poleceń

Ścieżki poleceń mogą włączyć obsługiwane rozwiązywanie SecretRef przez RPC migawki Gateway.

Istnieją dwa ogólne zachowania:

Inne uwagi:

• Odświeżanie migawki po rotacji sekretu backendu obsługuje 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 traktuj migracji jako ukończonej, dopóki ponowny audyt nie jest czysty. Jeśli audyt nadal zgłasza wartości plaintext w spoczynku, ryzyko dostępu agenta nadal istnieje, nawet gdy API runtime zwracają wartości zredagowane.

Jeśli zapiszesz plan zamiast zastosować go podczas configure, zastosuj ten zapisany plan za pomocą openclaw secrets apply --from <plan-path> przed ponownym audytem.

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:

• preflight musi zakończyć się powodzeniem przed trybem zapisu
• aktywacja runtime jest walidowana przed zatwierdzeniem
• apply aktualizuje pliki przy użyciu atomowej zamiany pliku i best-effort przywracania w razie niepowodzenia

Uwagi dotyczące zgodności legacy auth

W przypadku statycznych poświadczeń runtime nie zależy już od magazynu legacy auth w postaci plaintext.

• Źródłem poświadczeń runtime jest rozwiązana migawka w pamięci.
• Statyczne wpisy legacy api_key są usuwane po wykryciu.
• Zachowanie zgodności związane z OAuth pozostaje oddzielne.

Uwaga dotycząca Web UI

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

Powiązane

• Uwierzytelnianie — konfiguracja auth
• CLI: secrets — polecenia CLI
• Zmienne środowiskowe — priorytet środowiska
• Powierzchnia poświadczeń SecretRef — powierzchnia poświadczeń
• Kontrakt planu Secrets Apply — szczegóły kontraktu planu
• Bezpieczeństwo — postawa bezpieczeństwa