Zarządzanie sekretami

​

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.

​

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

• 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.

​

Granica dostępu agenta

• 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.

​

Filtrowanie aktywnych powierzchni

• 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

• 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.

​

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

• 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.

​

Kontrakt SecretRef

{ 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

{
  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

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

​

Przykłady integracji exec

{
  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 node
const { 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 --check
openclaw 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

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

​

Materiały uwierzytelniające SSH piaskownicy

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

• 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ń

​

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.

• 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)

​

Wyzwalacze aktywacji

• 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

• 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

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

• 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ń

• 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

openclaw secrets audit --check

openclaw secrets configure --apply

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

• 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

• Ź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

​

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