Sie bitten Claude Code, einen DNS-Eintrag anzulegen oder einen Worker zu deployen, und er antwortet, dass er dafür einen Cloudflare-API-Token braucht. Am einfachsten ist es, den Token aus dem Dashboard zu kopieren und in den Chat einzufügen. Der Agent legt sofort los, und genau deshalb machen es fast alle so.
Das Problem ist, dass der Chat nicht verschwindet. Das Gespräch mit dem Agenten wird auf der Festplatte gespeichert, mit jeder Nachricht vollständig an den Anbieter des Modells geschickt und landet bei jedem, dem Sie ein Log schicken, wenn Sie Hilfe brauchen. Der Token liegt an all diesen Stellen mit dabei.
Im Folgenden steht, wie wir das bei uns eingerichtet haben: Unser Agent deployt und ändert Zonen jeden Tag und hat den Token nie gesehen. Die Dokumentation von Cloudflare und Claude Code haben wir am 19. November 2026 geprüft.
Kurz gesagt sind es vier Schritte:
- Legen Sie einen Token an, der nur kann, was der Agent braucht.
- Legen Sie ihn in eine Datei und lassen Sie ein kleines Skript ihn an Ihre Werkzeuge weitergeben.
- Richten Sie einen Hook ein, der den Agenten diese Datei nicht öffnen lässt.
- Geben Sie eigene Tokens über die Zwischenablage hinein, nicht über den Chat.
Warum nicht in den Chat
Den Token in eine Nachricht einzufügen ist der offensichtliche Weg, ihn preiszugeben, aber nicht
der einzige. Bitten Sie den Agenten, „nachzusehen, was in .env steht“, liest er die Datei, und
ihr ganzer Inhalt landet genauso im Gespräch. Haben Sie zwei Agentenfenster in zwei Projekten
offen und schickt das eine dem anderen einen Schlüssel als Nachricht, bleibt der Schlüssel im
Verlauf beider.
Es gibt auch einen weniger offensichtlichen Fall. In Claude Code können Sie nach ! einen Befehl
eingeben, und das fühlt sich an wie Ihr eigenes Terminal. Die
Dokumentation sagt aber ausdrücklich, dass
dieser Modus “adds the command and its output to the conversation context”. Tippen Sie einen Token
in so einen Befehl, landet er im Gespräch, zusammen mit allem, was der Befehl ausgibt.
Schritt 1. Ein Token, der wenig kann
Beginnen Sie damit, was der Token kann, bevor Sie überlegen, wo er liegt. Der Global API Key ist für einen Agenten die falsche Wahl: Cloudflares eigene Seite sagt, er “has the exact same permissions as the user”, er kann also alles, was Sie können. Die eine Aufgabe, für die Sie ihn vielleicht noch brauchen, ist das Anlegen vieler Zonen auf einmal, beschrieben in der Anleitung zum Zonenlimit. Für alles andere, was ein Agent tut, nehmen Sie einen normalen API-Token mit Einschränkungen.
Cloudflares Token-Editor hat vier Einstellungen, die sich lohnen. Die ersten zwei stehen auf dieser Seite, die anderen zwei auf der Seite zum Einschränken von Tokens.
| Einstellung | Was Cloudflare sagt | Was Sie für einen Agenten wählen |
|---|---|---|
| Permissions | “Choose the permissions to grant within the policy.” | Nur was die Aufgabe braucht, Lesen, wo Lesen reicht |
| Resources | “specific accounts or zones” | Nur die Zonen, an denen der Agent arbeitet |
| Client IP Address Filtering | “Once an Is in rule is applied, the token can only be used from the defined IP addresses.” |
Die Adressen Ihres Büros oder Servers, in CIDR |
| TTL | “By default, tokens do not expire and are long lived.” | Ein Enddatum, das zur Aufgabe passt |
Prüfen Sie eine Berechtigung gesondert. Wer einen Token hat, kann über die API weitere anlegen: “you can create additional API tokens”. Die Berechtigung dahinter heißt API Tokens Write, und die Liste der Berechtigungen beschreibt sie mit “Grants write access to user’s API tokens”. Fließt ein Token mit dieser Berechtigung ab, kann man damit neue Tokens erzeugen, und den alten zu widerrufen hilft dann nicht mehr. Ein Agent braucht sie nie.
Cloudflare zeigt einen Token einmal (“The token secret is only shown once”), und neue Tokens
beginnen mit cfut_, was Cloudflare “scannable format” nennt, damit Secret-Scanner einen Token in
einem Repository finden. Das Gespräch mit einem Agenten liest aber kein Scanner. Steht ein Token
erst einmal darin, bleibt nur, ihn zu widerrufen und einen neuen anzulegen.
Schritt 2. Ein Skript gibt den Token weiter, nicht der Agent
Legen Sie den Token in eine Datei, die git ignoriert. Bei uns ist das .dev.vars, in vielen
Projekten .env. Dann brauchen Sie ein kleines Skript, das die Datei liest und das gewünschte
Programm startet, zum Beispiel wrangler, mit dem Token in dessen Umgebungsvariablen. Der Agent
ruft das Skript auf, wrangler bekommt den Token, und ins Gespräch kommt nur das Ergebnis. Dieser
Blog deployt genau so. Die kleinste Fassung des Skripts:
// with-token.mjs: node with-token.mjs <node script> [args...]
// Runs a Node script with the Cloudflare token from .dev.vars in its environment.
// Nothing from the file is printed; the token never appears on a command line.
import { spawnSync } from 'node:child_process';
import fs from 'node:fs';
const KEYS = ['CLOUDFLARE_API_TOKEN', 'CLOUDFLARE_ACCOUNT_ID'];
const env = { ...process.env };
for (const line of fs.readFileSync('.dev.vars', 'utf8').split(/\r?\n/)) {
const eq = line.indexOf('=');
const key = line.slice(0, eq).trim();
const value = line.slice(eq + 1).trim().replace(/^(['"])(.*)\1$/, '$2'); // KEY="value" too
if (eq > 0 && KEYS.includes(key)) env[key] = value;
}
const missing = KEYS.filter((k) => !env[k]);
if (missing.length) {
console.error(`.dev.vars has no ${missing.join(', ')}`);
process.exit(2);
}
const r = spawnSync(process.execPath, process.argv.slice(2), { stdio: 'inherit', env });
process.exit(r.status ?? 1);
Zum Prüfen bitten Sie den Agenten,
node with-token.mjs node_modules/wrangler/bin/wrangler.js whoami auszuführen. Wrangler antwortet,
er sei “logged in with an Account API Token”, gelesen “from the CLOUDFLARE_API_TOKEN environment
variable”, und der Token selbst steht nirgends in der Antwort. Das Skript nimmt aus der Datei nur
die zwei Variablen, die es braucht, und startet das Programm direkt, ohne Shell, also landet der
Token auch nicht in Ihrer Befehlshistorie.
Damit der Agent an das Skript denkt, schreiben Sie eine Zeile in die CLAUDE.md oder
AGENTS.md des Projekts: wrangler über node with-token.mjs starten, die Token-Datei nie öffnen.
Schritt 3. Lassen Sie den Agenten die Token-Datei nicht öffnen
Eine Zeile in den Anweisungen ist eine Bitte. Ein Agent kann sie vergessen, gerade in einer langen
Sitzung, und eines Tages cat .env ausführen, um „die Einstellungen zu prüfen“. Dafür gibt es
Hooks: Claude Code führt einen PreToolUse-Hook vor jeder Aktion des Agenten aus, und der Hook
kann die Aktion ablehnen. Codex hat ebenfalls Hooks, führt einen fremden aber erst aus, nachdem Sie ihm in
/hooks vertraut haben.
Unser Hook sieht nach, welche Datei der Agent will und welchen Befehl er ausführen möchte, und
lehnt ab, wenn darin eine Geheimnisdatei vorkommt: .env und .env.* (aber nicht
.env.example), .dev.vars, alles in einem Ordner .secrets, *.pem, id_rsa. Er liegt im
offenen Repository secret-handoff, und im README
stehen fertige Einstellungen für Claude Code und Codex.
Bei der Einrichtung passieren leicht zwei Fehler.
- Der Hook muss jedes Werkzeug abdecken, das eine Datei lesen kann. In den Einstellungen von
Claude Code ist das der Matcher, eine Liste von Werkzeugnamen. Unter Windows führt der Agent
Befehle über
PowerShellaus, nicht überBash; steht nurBashin der Liste, wirdcat .envblockiert undGet-Content .envgeht durch. Ein weiteres Werkzeug, das gern vergessen wird, istGrep: Es gibt die gefundenen Zeilen aus, liest also ebenfalls Dateien. Unsere Liste lautetRead|Edit|Write|Grep|Bash|PowerShell. - Prüfen Sie, dass er wirklich blockiert. Unter Windows startet Claude Code Hooks unter
Umständen über PowerShell, und PowerShell macht aus dem Exitcode 2 eine 1. Claude Code behandelt
1 als Hook-Fehler und lässt die Aktion durch. Wir hielten uns für geschützt, bis wir den Agenten
baten,
.envzu lesen, und zusahen, wie er es tat.
Das ist der einzige Test, der zählt: von Hand, mit einem echten Agenten. Bitten Sie ihn, eine
Datei aus .secrets zu lesen und Ihnen .env zu zeigen. Beides muss mit einer Ablehnung enden.
So haben wir unseren eigenen Fehler gefunden. Der Hook sah nur auf den Dateinamen am Ende eines
Pfads, also war der ganze Ordner .secrets gesperrt, während cat .secrets/token.txt
durchging, weil token.txt ein harmloser Name ist. Diese Version lief auf diesem Blog, während
wir diese Anleitung schrieben.
Wenn Sie einen eigenen Hook schreiben, testen Sie ihn noch an ein paar Fällen, die das Review unseres Hooks gefunden hat:
- ein erlaubter Befehl, ein Zeilenumbruch und ein zweiter Befehl wie
cat .env; - ein Pfad, der nur so aussieht wie der Pfad des vertrauenswürdigen Skripts, etwa
evil.agents/skills/…/handoff.sh; - eine Suche mit
Grepundglob: .env.
Schritt 4. Den eigenen Token hineingeben, ohne ihn irgendwo einzufügen
Bleibt die Frage, wie ein Token aus dem Cloudflare-Dashboard in die Datei kommt. Die Datei zu
öffnen und ihn von Hand einzufügen ist in Ordnung. Wenn Sie ohnehin im Fenster des Agenten
arbeiten, geht es einfacher: Kopieren Sie den Token und führen Sie in der Eingabe des Agenten
diesen Befehl aus demselben Repository aus (unter macOS und Linux python3 statt py -3):
! py -3 $HOME/.agents/skills/secret-handoff/handoff.py put cloudflare-token-blog --clipboard
Ins Gespräch kommt nur diese Zeile, und sie enthält nur den Namen cloudflare-token-blog. Das
Skript nimmt den Token aus der Zwischenablage, speichert ihn in einem gesperrten Ordner in Ihrem
Home-Verzeichnis und leert die Zwischenablage, wenn sie noch denselben Token enthält. Die Antwort
zeigt Namen und Länge, nicht den Wert. Sie warnt auch, dass eine Kopie im Verlauf der
Zwischenablage bleiben kann: Win+V unter Windows, der Verlauf unter macOS, ein Clipboard-Manager
unter Linux. Den räumen Sie selbst auf. Dann sagen Sie dem Agenten, wohin der Token gehört, und er
verschiebt ihn mit take in die Datei des Projekts, wieder ohne ihn zu sehen.
Dasselbe Werkzeug hilft, wenn ein Schlüssel in einem anderen Projekt gebraucht wird. Angenommen, ein Agent hat in einem Fenster gerade einen API-Schlüssel ausgestellt, und benutzen wird ihn der Agent im nächsten Projekt. Den Schlüssel als Nachricht zu schicken, hieße, ihn wieder in ein Gespräch zu legen. Stattdessen legt der erste Agent den Schlüssel in denselben gesperrten Ordner, und der zweite holt ihn heraus:
handoff.sh put <name> --from <file> [--line N | --key VAR] [--remove-source]
handoff.sh take <name> --into <secret file> [--key VAR]
handoff.sh drop <name>
handoff.sh list
Die Nachricht zwischen den Projekten enthält nur den Namen des Schlüssels und wofür er ist. take
schreibt den Schlüssel nur in eine Datei, die der Hook schützt, und mit --remove-source behält
der Absender keine Kopie. Einen Schlüssel, den niemand abholt, löscht drop, ohne ihn zu lesen.
Der Hook erlaubt einen einzelnen Aufruf dieses Skripts und lässt keinen zweiten Befehl daran
anhängen. Damit der Hook das Skript erkennt, klonen Sie das Repository an den Ort, den das README
nennt:
git clone https://github.com/investblog/secret-handoff ~/.agents/skills/secret-handoff
Wovor das nicht schützt
Das alles ist ein Sicherheitsgurt gegen den Fehler eines Agenten. Einen Agenten, der es darauf
anlegt, an den Schlüssel zu kommen, hält er nicht auf. Der Hook sieht den Text eines Befehls, also
übersieht er einen Pfad, der erst beim Ausführen entsteht (.sec''rets, ein Platzhalter, eine
Variable). Er hilft nicht mehr, wenn der Token selbst im Text einer Anfrage steht; dafür brauchen
Sie eine zweite Prüfung, einen Commit-Hook, der nach Geheimnissen sucht. Der Hook braucht Python:
Findet er kein Python, lässt er alles durch, statt den Agenten ganz auszusperren. In Codex liest der
Hook den ganzen Text eines Patches, also lehnt er auch eine Änderung an einem Dokument ab, das
.env nur erwähnt; machen Sie diese Änderung mit einem anderen Werkzeug.
Und zu !: Die Befehlszeile landet immer im Gespräch. Die Zwischenablage hält den Wert heraus,
aber Ihre Befehlshistorie und den Verlauf der Zwischenablage räumen Sie selbst auf.
Wenn Sie selbst eine API für Agenten bauen
Bisher ging es darum, wer einen Schlüssel sieht. Wenn Sie einen Dienst bauen, den Agenten aufrufen werden, etwa einen MCP-Server auf Workers, können Sie außerdem dafür sorgen, dass ein abgeflossener Schlüssel wenig wert ist. Im quelloffenen clx funktioniert das so: Ein Schlüssel kann nur aus einem Konto ausgestellt werden, in das sich ein Mensch eingeloggt hat, also kann ein Schlüssel keinen anderen ausstellen. Jeder Schlüssel hat eigene Berechtigungen und auf Wunsch eine Liste erlaubter Cloudflare-Konten und IP-Adressen. Der Server speichert nur einen Hash und zeigt den Schlüssel einmal. Und das Skript, das einen Schlüssel ausstellt, widerruft ihn selbst, wenn die Antwort des Servers verloren ging oder der Schlüssel nicht gespeichert werden konnte, sodass kein gültiger Schlüssel unbemerkt herumliegt.
Wann Sie clx oder 301.st brauchen
Wenn das Cloudflare-Konto Ihres ist und Sie einen Agenten betreiben, reichen ein enger Token, das Skript und der Hook. Das alles ist kostenlos.
clx zählt Besuche, Klicks auf Kurzlinks und QR-Scans auf Ihren eigenen Seiten, mit einem Worker und einer D1-Datenbank, die es in Ihr Cloudflare-Konto installiert. Seine API-Schlüssel funktionieren wie oben beschrieben, Sie können sie einem Agenten also ohne Sorge geben.
301.st macht dasselbe mit dem Cloudflare-Token selbst. Sie legen einen vorübergehenden Token an, der Tokens erstellen darf. 301.st benutzt ihn einmal, um seinen eigenen Arbeitstoken zu erzeugen, mit einer festen Liste von Berechtigungen, in der das Erstellen von Tokens nicht vorkommt, und mit einem Enddatum in fünf Jahren. Dann löscht es den vorübergehenden Token und speichert den Arbeitstoken verschlüsselt. Lehnt Cloudflare das Löschen ab, protokolliert 301.st das, und der vorübergehende Token bleibt in Ihrem Dashboard, damit Sie ihn entfernen. Von da an betreibt 301.st Weiterleitungen, Traffic-Regeln und Zonen für Ihr ganzes Portfolio mit diesem Arbeitstoken.