Zarządzanie sekretami

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

# Cele i model środowiska uruchomieniowego

Sekrety są rozwiązywane do migawki środowiska uruchomieniowego w pamięci.

• Rozwiązywanie odbywa się eager podczas aktywacji, a nie lazy na ścieżkach żądań.
• Uruchamianie kończy się szybkim niepowodzeniem, gdy faktycznie aktywnego SecretRef nie można rozwiązać.
• Przeł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 danymi wejściowymi SecretRef) przerywają aktywację przed podmianą środowiska uruchomieniowego.
• Żądania środowiska uruchomieniowego odczytują wyłącznie aktywną migawkę w pamięci.
• Po pierwszej udanej aktywacji/wczytaniu konfiguracji ścieżki kodu środowiska uruchomieniowego nadal odczytują tę aktywną migawkę w pamięci, dopóki udane przeładowanie jej nie podmieni.
• Ścieżki dostarczania wychodzącego również odczytują tę aktywną migawkę (na przykład dostarczanie odpowiedzi/wątków Discord i wysyłki akcji Telegram); nie rozwiązują ponownie SecretRefs przy każdej wysyłce.

Dzięki temu awarie dostawcy sekretów nie trafiają na krytyczne ścieżki obsługi żądań.

# Filtrowanie aktywnej powierzchni

SecretRefs są weryfikowane tylko na faktycznie aktywnych powierzchniach.

• Włączone powierzchnie: nierozwiązane referencje blokują uruchomienie/przeładowanie.
• Nieaktywne powierzchnie: nierozwiązane referencje nie blokują uruchomienia/przeładowania.
• Nieaktywne referencje 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, uruchamianie/przeładowanie Gateway jawnie loguje stan powierzchni:

• active: SecretRef jest częścią faktycznej powierzchni uwierzytelniania i musi zostać rozwiązany.
• inactive: SecretRef jest ignorowany w tym środowisku uruchomieniowym, ponieważ wygrywa inna powierzchnia uwierzytelniania albo zdalne uwierzytelnianie jest wyłączone/nieaktywne.

Te wpisy są logowane z SECRETS_GATEWAY_AUTH_SURFACE i zawierają przyczynę używaną przez zasadę aktywnej powierzchni, dzięki czemu widać, dlaczego dane uwierzytelniające potraktowano jako aktywne lub nieaktywne.

# Wstępna kontrola referencji podczas onboardingu

Gdy onboarding działa w trybie interaktywnym i wybierzesz przechowywanie SecretRef, OpenClaw wykonuje wstępną walidację przed zapisaniem:

• Referencje env: waliduje nazwę zmiennej env i potwierdza, że podczas konfiguracji widoczna jest niepusta wartość.
• Referencje dostawcy (file lub exec): waliduje wybór dostawcy, rozwiązuje id i sprawdza typ rozwiązanej wartości.
• Ścieżka ponownego użycia szybkiego startu: gdy gateway.auth.token jest już SecretRef, onboarding rozwiązuje go przed inicjalizacją sondy/panelu (dla referencji env, file i exec), używając tego samego mechanizmu szybkiego przerywania przy błędzie.

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

# Kontrakt SecretRef

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

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

# Konfiguracja dostawców

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

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

# Zmienne środowiskowe serwera MCP

Zmienne env serwera MCP skonfigurowane przez plugins.entries.acpx.config.mcpServers obsługują SecretInput. Dzięki temu klucze API i tokeny nie trafiają do konfiguracji w tekście jawnym:

{
  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 w tekście jawnym nadal działają. Referencje szablonów env, takie jak ${MCP_SERVER_API_KEY}, oraz obiekty SecretRef są rozwiązywane podczas aktywacji Gateway, zanim proces serwera MCP zostanie uruchomiony. Tak jak w przypadku innych powierzchni SecretRef, nierozwiązane referencje blokują aktywację tylko wtedy, gdy plugin acpx jest faktycznie aktywny.

# Materiał uwierzytelniania SSH piaskownicy

Główny backend piaskownicy ssh również obsługuje SecretRefs dla materiału uwierzytelniania 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 środowiska uruchomieniowego:

• 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 efektywnym backendem sandboxa nie jest ssh, te odwołania pozostają nieaktywne i nie blokują uruchamiania.

# Obsługiwany zakres poświadczeń

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

• Zakres poświadczeń SecretRef

# Wymagane zachowanie i kolejność pierwszeństwa

• Pole bez odwołania: bez zmian.
• Pole z odwołaniem: wymagane na aktywnych powierzchniach podczas aktywacji.
• Jeśli obecne są zarówno tekst jawny, jak i odwołanie, odwołanie ma pierwszeństwo na obsługiwanych ścieżkach pierwszeństwa.
• Sentinel redakcji __OPENCLAW_REDACTED__ jest zarezerwowany do 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 środowiska wykonawczego)
• REF_SHADOWED (ustalenie audytu, gdy poświadczenia z auth-profiles.json mają pierwszeństwo przed odwołaniami z openclaw.json)

Zachowanie zgodności Google Chat:

• serviceAccountRef ma pierwszeństwo przed tekstem jawnym serviceAccount.
• Wartość tekstu jawnego jest ignorowana, gdy ustawione jest sąsiednie odwołanie.

# Wyzwalacze aktywacji

Aktywacja sekretów uruchamia się przy:

• Uruchomieniu (kontrola wstępna plus końcowa aktywacja)
• Ścieżce przeładowania konfiguracji z zastosowaniem na gorąco
• Ścieżce przeładowania konfiguracji ze sprawdzeniem restartu
• Ręcznym przeładowaniu przez secrets.reload
• Kontroli wstępnej RPC zapisu konfiguracji Gateway (config.set / config.apply / config.patch) pod kątem możliwości rozwiązania SecretRef z aktywnej powierzchni w przesłanym ładunku konfiguracji przed utrwaleniem edycji

Kontrakt aktywacji:

• Sukces atomowo podmienia migawkę.
• Błąd uruchamiania przerywa start gatewaya.
• Błąd przeładowania w środowisku wykonawczym zachowuje ostatnią znaną dobrą migawkę.
• Błąd kontroli wstępnej RPC zapisu odrzuca przesłaną konfigurację i pozostawia zarówno konfigurację na dysku, jak i aktywną migawkę środowiska wykonawczego bez zmian.
• Podanie jawnego tokenu kanału dla pojedynczego wywołania do wychodzącego wywołania pomocnika/narzędzia nie wyzwala aktywacji SecretRef; punktami aktywacji pozostają uruchomienie, przeładowanie i jawne secrets.reload.

# Sygnały degradacji i odzyskania

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: środowisko wykonawcze zachowuje ostatnią znaną dobrą migawkę.
• Odzyskany: emitowane raz po następnej udanej aktywacji.
• Powtarzające się błędy, gdy stan jest już zdegradowany, zapisują ostrzeżenia w dzienniku, ale nie zalewają zdarzeniami.
• Szybkie przerwanie uruchamiania nie emituje zdarzeń degradacji, ponieważ środowisko wykonawcze nigdy nie stało się aktywne.

# Rozwiązywanie ścieżki polecenia

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

Istnieją dwa szerokie 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

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

# Jednokierunkowa polityka bezpieczeństwa

Model bezpieczeństwa:

• kontrola wstępna musi zakończyć się powodzeniem przed trybem zapisu
• aktywacja w środowisku wykonawczym jest weryfikowana przed zatwierdzeniem
• apply aktualizuje pliki przy użyciu atomowej podmiany pliku i najlepszej możliwej próby 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 tekście jawnym.

• Źródłem poświadczeń środowiska wykonawczego jest rozwiązana migawka w pamięci.
• Starsze statyczne wpisy api_key są czyszczone 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 uwierzytelniania
• CLI: secrets — polecenia CLI
• Zmienne środowiskowe — pierwszeństwo środowiska
• Zakres poświadczeń SecretRef — zakres poświadczeń
• Kontrakt planu Secrets Apply — szczegóły kontraktu planu
• Bezpieczeństwo — postawa bezpieczeństwa