OpenClaw SecretRef: Anmeldedaten sicher konfigurieren

Jeder Entwickler kennt das: Man will seine API-Keys sicher verwalten, aber landet am Ende doch wieder bei einem Mix aus Umgebungsvariablen und manuellen Configs. Wenn du Ordnung in dein Secret-Management bringen willst, ist die SecretRef Credential Surface genau das Richtige für dich. Hier erfährst du, welche Credentials du über OpenClaw sicher handhaben kannst und wo das System bewusst Grenzen zieht.

Diese Seite definiert die offizielle SecretRef Credential Surface.

Scope-Absicht:

• Im Scope: Rein benutzergelieferte Credentials, die OpenClaw nicht selbst erstellt oder rotiert.
• Nicht im Scope: Zur Laufzeit erstellte oder rotierende Credentials, OAuth-Refresh-Material und Session-ähnliche Artefakte.

Unterstützte Credentials

openclaw.json targets (secrets configure + secrets apply + secrets audit)

• models.providers.*.apiKey
• models.providers.*.headers.*
• skills.entries.*.apiKey
• agents.defaults.memorySearch.remote.apiKey
• agents.list[].memorySearch.remote.apiKey
• talk.apiKey
• talk.providers.*.apiKey
• messages.tts.providers.*.apiKey
• tools.web.fetch.firecrawl.apiKey
• plugins.entries.brave.config.webSearch.apiKey
• plugins.entries.google.config.webSearch.apiKey
• plugins.entries.xai.config.webSearch.apiKey
• plugins.entries.moonshot.config.webSearch.apiKey
• plugins.entries.perplexity.config.webSearch.apiKey
• plugins.entries.firecrawl.config.webSearch.apiKey
• plugins.entries.tavily.config.webSearch.apiKey
• tools.web.search.apiKey
• tools.web.x_search.apiKey
• gateway.auth.password
• gateway.auth.token
• gateway.remote.token
• gateway.remote.password
• cron.webhookToken
• channels.telegram.botToken
• channels.telegram.webhookSecret
• channels.telegram.accounts.*.botToken
• channels.telegram.accounts.*.webhookSecret
• channels.slack.botToken
• channels.slack.appToken
• channels.slack.userToken
• channels.slack.signingSecret
• channels.slack.accounts.*.botToken
• channels.slack.accounts.*.appToken
• channels.slack.accounts.*.userToken
• channels.slack.accounts.*.signingSecret
• channels.discord.token
• channels.discord.pluralkit.token
• channels.discord.voice.tts.providers.*.apiKey
• channels.discord.accounts.*.token
• channels.discord.accounts.*.pluralkit.token
• channels.discord.accounts.*.voice.tts.providers.*.apiKey
• channels.irc.password
• channels.irc.nickserv.password
• channels.irc.accounts.*.password
• channels.irc.accounts.*.nickserv.password
• channels.bluebubbles.password
• channels.bluebubbles.accounts.*.password
• channels.feishu.appSecret
• channels.feishu.encryptKey
• channels.feishu.verificationToken
• channels.feishu.accounts.*.appSecret
• channels.feishu.accounts.*.encryptKey
• channels.feishu.accounts.*.verificationToken
• channels.msteams.appPassword
• channels.mattermost.botToken
• channels.mattermost.accounts.*.botToken
• channels.matrix.accessToken
• channels.matrix.password
• channels.matrix.accounts.*.accessToken
• channels.matrix.accounts.*.password
• channels.nextcloud-talk.botSecret
• channels.nextcloud-talk.apiPassword
• channels.nextcloud-talk.accounts.*.botSecret
• channels.nextcloud-talk.accounts.*.apiPassword
• channels.zalo.botToken
• channels.zalo.webhookSecret
• channels.zalo.accounts.*.botToken
• channels.zalo.accounts.*.webhookSecret
• channels.googlechat.serviceAccount via sibling serviceAccountRef (compatibility exception)
• channels.googlechat.accounts.*.serviceAccount via sibling serviceAccountRef (compatibility exception)

auth-profiles.json targets (secrets configure + secrets apply + secrets audit)

• profiles.*.keyRef (type: "api_key"; unsupported when auth.profiles.<id>.mode = "oauth")
• profiles.*.tokenRef (type: "token"; unsupported when auth.profiles.<id>.mode = "oauth")

Anmerkungen:

• Auth-Profile Plan-Targets benötigen eine agentId.
• Plan-Einträge zielen auf profiles.*.key / profiles.*.token ab und schreiben Sibling-Refs (keyRef / tokenRef).
• Auth-Profile-Refs sind in der Runtime-Resolution und Audit-Coverage enthalten.
• OAuth Policy Guard: auth.profiles.<id>.mode = "oauth" lässt sich nicht mit SecretRef-Inputs für dieses Profil kombinieren. Startup/Reload und Auth-Profile-Resolution schlagen sofort fehl, wenn diese Policy verletzt wird.
• Für SecretRef-verwaltete Model-Provider speichern generierte agents/*/agent/models.json Einträge Non-Secret-Marker (keine aufgelösten Secret-Werte) für apiKey/Header-Surfaces.
• Marker-Persistenz ist Source-Authoritative: OpenClaw schreibt Marker aus dem aktiven Source-Config-Snapshot (vor der Resolution), nicht aus den aufgelösten Runtime-Secret-Werten.
• Für Web Search:
  • Im expliziten Provider-Modus (tools.web.search.provider gesetzt) ist nur der Key des gewählten Providers aktiv.
  • Im Auto-Modus (tools.web.search.provider nicht gesetzt) ist nur der erste Provider-Key aktiv, der nach Priorität aufgelöst wird.
  • Im Auto-Modus werden nicht gewählte Provider-Refs als inaktiv behandelt, bis sie ausgewählt werden.
  • Legacy tools.web.search.* Provider-Pfade werden während des Kompatibilitätsfensters noch aufgelöst, aber die offizielle SecretRef Surface ist plugins.entries.<plugin>.config.webSearch.*.

Nicht unterstützte Credentials

Credentials, die nicht im Scope liegen:

• commands.ownerDisplaySecret
• hooks.token
• hooks.gmail.pushToken
• hooks.mappings[].sessionKey
• auth-profiles.oauth.*
• channels.discord.threadBindings.webhookToken
• channels.discord.accounts.*.threadBindings.webhookToken
• channels.whatsapp.creds.json
• channels.whatsapp.accounts.*.creds.json

Begründung:

• Diese Credentials werden generiert, rotiert, sind Session-basiert oder gehören zu OAuth-Klassen. Sie passen nicht zum Read-only-Ansatz der externen SecretRef Resolution.

Nächste Schritte

• Secrets konfigurieren
• Secrets anwenden

AI Setup Assistant