API klíče a proměnné prostředí

Připojení je skoro hotovo. Agent napsal konfiguraci, pojmenoval službu a zastavil se na jednom poli - API key. Služba vydala dlouhý řetězec a z něj samotného není poznat, kam ho dát. Do chatu? Do souboru vedle kódu? Přímo do konfigurace, aby byla jistota, že to bude fungovat?

Rozebereme si to na jednom modelu. Podíváme se, kde se hodnota nastavuje, jaký proces ji obdrží a jak se ujistit, že je vše správně nakonfigurováno, aniž bychom ukazovali samotný tajný klíč. Model je stejný pro místní spuštění, pro připojení MCP i pro publikovanou aplikaci - mění se jen to, čí prostředí nastavujeme.

Co dává přístupový klíč

Klíč spojuje požadavek s účtem nebo projektem a s právy, která vám byla přidělena. Služba podle něj pozná, kdo požadavek poslal, co tento odesílatel smí a kolik toho už vyžádal. Přesný význam klíče určuje konkrétní služba. Někde to znamená přístup k celému účtu, jinde jen k jednomu projektu a jen pro čtení.

Vedle slova "klíč" se v návodech objevuje token. V každodenních textech se často používají jako synonyma, ale podrobnosti mechanismu se liší. Jedná se o způsob získání, dobu platnosti a sadu práv. Za úplná synonyma je raději nepovažujte - co přesně služba vydá, je napsáno v její dokumentaci.

Proč vás služba vůbec potřebuje rozlišovat, je nejlépe vidět na příkladu z běžného života. Vytvořili jste si účet, vybrali si tarif s měsíčním limitem požadavků a dostali klíč. Pak služba podle tohoto klíče počítá vaše požadavky, porovnává je s limitem, a pokud je tarif placený, vystaví vám fakturu. Klíč, který se dostal do cizích rukou, znamená, že limit a faktura jdou někomu jinému.

Klíč sám nerozhoduje. Dává službě odkaz na nastavení vlastníka a teprve služba rozhoduje, zda je konkrétní požadavek povolen a zda ho má odečíst z limitu.

Existují i hodnoty, které služba výslovně označuje jako veřejné - ty patří právě do kódu stránky. Veřejnou hodnotu od tajné podle názvu proměnné nerozlišíte. Účel je popsán v dokumentaci, tam je potřeba se podívat. Ve všech příkladech níže jsou zjevné zástupné hodnoty jako fc-EXAMPLE-0000000000, skutečný klíč tak nevypadá.

Kde může aplikace uchovávat tajný klíč

Představte si takovou situaci. Přidali jste klíč přímo do kódu stránky, spustili projekt a dostali odpověď z API. Všechno funguje. Po publikování se aplikace také otevře, požadavky procházejí - zdá se, že je hotovo.

Jenže spolu s kódem dostane klíč i prohlížeč každého návštěvníka. Stačí otevřít vývojářské nástroje, najít ho v JavaScriptu nebo v požadavku a zkopírovat. Pak může kdokoli posílat vlastní požadavky vaším jménem. Budou čerpat váš limit, dokud služba nezačne odmítat už vaše požadavky.

Problém není v konkrétním nástroji pro sestavení. Všechno, co stránka předala prohlížeči, má jeho uživatel k dispozici: HTML, styly, JavaScript, adresy a hlavičky požadavků. I když se klíč při sestavení vzal z lokálního .env, po dosazení do JavaScriptu odjel k návštěvníkovi spolu se zbytkem kódu.

Backend je kód, který běží na serveru. Návštěvník dostává jeho odpovědi, ale ne zdrojový kód ani proměnné prostředí serverového procesu. Proto může backend držet klíč u sebe a volat externí službu jménem aplikace.

Schéma požadavku se změní. Prohlížeč pošle vašemu backendu běžný požadavek bez tajného klíče. Backend načte klíč ze svého prostředí, přidá jej do samostatného požadavku na API a vrátí prohlížeči jen výsledek.

Nyní návštěvník vidí adresu backendu a data odpovědi, ale ne klíč externí služby. Tajný klíč zůstává u procesu, který ho používá.

Tajný klíč má dva možné vlastníky:

• místní proces - Claude Code s připojenou integrací, skript nebo dev server. Běží na vašem počítači a klíč dostává tamtéž;
• backend publikované aplikace - kód na serveru, který sám volá externí API. Jeho prostředí se nastavuje v panelu hostingu.

Jde o dvě samostatná nastavení. Klíč z prostředí vašeho počítače se na hostingu sám neobjeví, i když se služba a název proměnné shodují.

Přesunutí klíče na backend jej skryje před prohlížečem, ale veřejný backend je i tak potřeba chránit před cizími požadavky.

Jak funguje proměnná prostředí

Proměnná prostředí je pojmenovaná hodnota, kterou program obdrží při spuštění. Má název, například FIRECRAWL_API_KEY, a hodnotu, tedy ten dlouhý řetězec. V konfiguracích a v kódu se píše název; hodnota žije zvlášť a vedle kódu se neukládá.

Odkud si ji program vezme. Program spuštěný z terminálu dědí prostředí tohoto terminálu. Nastavili jste proměnnou v okně, spustili z něj Claude Code - Claude Code ji vidí. Otevřeli jste druhé okno a nastavili tam proměnnou - na už běžící proces to nemá vliv, prostředí dostal při startu.

Odtud nejčastější důvod stížnosti "klíč je přece nastavený, a nefunguje". Hodnota byla nastavena v jiném okně nebo až po spuštění. Řeší se to restartem procesu z terminálu, kde proměnná existuje.

Ukázková varianta se zjevně fiktivní hodnotou:

# bash: proměnná pro aktuální terminál
export FIRECRAWL_API_KEY=fc-EXAMPLE-0000000000

# PowerShell: totéž
$env:FIRECRAWL_API_KEY = "fc-EXAMPLE-0000000000"

Se zástupnou hodnotou v ukázkovém příkladu se to tak psát dá. Skutečný klíč byste takto zadávat neměli. Celý řetězec skončí v historii příkazů a zůstane tam i poté, co terminál zavřete. Pro skutečnou hodnotu existuje zadání bez echa - řetězec vložíte, na obrazovce se nic neobjeví a do historie se dostane jen samotný příkaz:

# bash: hodnota se zadává skrytě
read -s -r FIRECRAWL_API_KEY
export FIRECRAWL_API_KEY

# PowerShell: skryté zadání a rozbalení hodnoty do proměnné prostředí
$secure = Read-Host "FIRECRAWL_API_KEY" -AsSecureString
$env:FIRECRAWL_API_KEY = [System.Net.NetworkCredential]::new('', $secure).Password

Nastavení je potřeba kontrolovat tak, aby se hodnota neobjevila na obrazovce, v logu ani na snímku obrazovky. Na otázku "je nastaveno, nebo ne" stačí dva řádky:

# bash
[ -n "$FIRECRAWL_API_KEY" ] && echo "nastaveno" || echo "není nastaveno"

# PowerShell
if ($env:FIRECRAWL_API_KEY) { "nastaveno" } else { "není nastaveno" }

Délku ani první znaky vypisovat nemusíte. Kontrole to nic nepřidá a kus klíče už je součástí tajemství.

Způsobů, jak nastavit proměnnou natrvalo, je hodně a v každém systému jsou jiné. Zabývat se jimi teď nemusíte: pro místní práci stačí terminál a na hostingu se proměnné nastavují v jeho vlastním panelu.

Proč jsou potřeba .env a .env.example

Ruční nastavování proměnných v každém novém terminálu rychle omrzí, a tak se hodnoty ukládají do textového souboru .env. Jeden řádek v něm uchovává jeden pár názvu a hodnoty.

Nejčastěji se přehlíží důležitý detail. Soubor sám o sobě nic nenastavuje. Někdo ho musí přečíst a rozložit hodnoty do prostředí procesu - aplikace, knihovna nebo launcher, který váš program spouští. Vytvořit .env a počítat s tím, že si ho teď vezme jakýkoli program, nejde. Co přesně soubor ve vašem případě načítá, je lepší zjistit přímo, ne odhadovat.

Vedle něj obvykle leží další dva soubory:

# .env - zůstane jen na vašem počítači
FIRECRAWL_API_KEY=fc-EXAMPLE-0000000000

# .env.example - šablona pro ty, kdo otevřou projekt
# hodnoty jsou prázdné, jsou tu jen názvy
FIRECRAWL_API_KEY=

# .gitignore
.env

Smysl rozdělení je jednoduchý. .env.example odpovídá na otázku "které proměnné tento projekt potřebuje" a klidně může být v repozitáři, protože v něm žádné hodnoty nejsou. Skutečné klíče se do něj nepřenášejí ani dočasně.

Pokud s Gitem zatím nepracujete, stačí si tady zapamatovat roli .gitignore. Uvádí soubory, které se nemají přidávat do repozitáře. Podrobně práci s Gitem a .gitignore si vysvětlíme na úrovni 13.

A teď past s .gitignore, do které se lidé chytají pravidelně. Pravidlo platí jen pro soubory, které Git ještě nesleduje. Pokud byl .env někdy commitnutý, přidání řádku do .gitignore ho z Gitu neodpojí. Soubor zůstane ve správě verzí a jeho změny se budou do commitů dostávat i dál. Dokumentace Gitu to říká přímo. Soubory, které Git již sleduje, pravidla ignorování neovlivňují. Dokumentace gitignore.

Hlavní podmínka je na schématu uprostřed. Tentýž řádek v .gitignore pomáhá jen tehdy, když .env není sledovaný. Pro už sledovaný soubor je potřeba samostatný krok.

Proto se před zapsáním skutečného tajemství do souboru vyplatí ověřit, že o něm Git neví. git status ukáže, zda se soubor objevuje ve změnách. Pokud už je sledovaný, sledování se zruší příkazem git rm --cached .env a tato změna se commitne - soubor zůstane na disku, ale vypadne ze správy verzí.

Jen počítejte s tím, že to ovlivní budoucí commity. Hodnota, která se už dostala do historie, tam zůstane a řešit ji je potřeba jinak - o tom níže.

Jak předat klíč připojení MCP

MCP je způsob, jak připojit externí nástroj ke Claude Code. Připojení se popisuje v souboru .mcp.json a tento soubor obvykle leží v repozitáři spolu s projektem, takže ho vidí celý tým. Tajemství v něm tedy být nesmí.

Minimální připojení služby Firecrawl přes HTTP vypadá takto:

{
  "mcpServers": {
    "firecrawl": {
      "type": "http",
      "url": "https://mcp.firecrawl.dev/v2/mcp",
      "headers": {
        "Authorization": "Bearer ${FIRECRAWL_API_KEY}"
      }
    }
  }
}

Klíč v souboru není. V hlavičce stojí ${FIRECRAWL_API_KEY} - odkaz na proměnnou prostředí podle názvu. Claude Code sem dosadí hodnotu z prostředí procesu, ve kterém běží. Do repozitáře putuje název, hodnotu má každý svou. Claude Code umí tuto substituci provádět v polích url, headers, env, command a args. Claude Code o MCP.

Na schématu je vidět, že se v hlavičce požadavku potkávají dvě věci z různých míst. Šablona hlavičky přichází ze sdílené konfigurace a hodnota se dosazuje z prostředí procesu. V žádném kroku se klíč nezapisuje do souboru, který putuje do repozitáře.

Adresa a způsob předání klíče se berou z dokumentace samotné služby. U Firecrawlu je to hlavička Authorization a dokumentace výslovně žádá nevkládat klíč do MCP adresy. Důvod je jednoduchý. Adresa je obyčejný text, dostane se do konfigurace, do logů i do historie příkazů a spolu s ní tam skončí i klíč.

Některé služby podporují přihlášení přes prohlížeč. Klient sám otevře přihlašovací stránku a API key ručně předávat vůbec nemusíte. Firecrawl má pro to vyhrazenou samostatnou adresu. Dokumentace Firecrawlu o MCP.

Pokud nástroj neodpovídá, kontrolujte postupně:

1. název proměnné v konfiguraci a název, který jste nastavili, se shodují do posledního znaku;
2. hodnota je nastavená v procesu, ze kterého je Claude Code spuštěný;
3. proces byl po nastavení proměnné restartován.

Když proměnná chybí, Claude Code tiše nespadne. Načte konfiguraci, nechá text ${FIRECRAWL_API_KEY} nedosazený a vypíše varování s názvem chybějící proměnné. Samotná hodnota se přitom nikde nevypisuje, takže je diagnostika bezpečná. Vypisovat kvůli hledání problému celé prostředí rozhodně není potřeba.

Pokud klíč už unikl

Běžná situace. Klíč skončil ve zprávě, v commitu nebo na snímku obrazovky. Panikařit není proč, ale odkládat se to taky nevyplácí. Postup je následující:

1. zneplatnit nebo vyměnit klíč v účtu služby. Je to jediný krok, po kterém starý řetězec přestane cokoli otevírat;
2. nastavit novou hodnotu tam, kde je potřeba: lokálně, na hostingu, v nastavení připojení;
3. vyřešit místo, kde klíč unikl - smazat zprávu, opravit soubor, uzavřít přístup;
4. podívat se v účtu, jak byl klíč používán a co služba ukazuje u útrat.

Pořadí je právě takové a první krok se nepřesouvá. Smazaná zpráva ani nový commit přes starý z dřívějšího tajemství bezpečné neudělají. Zprávu už mohl někdo přečíst, repozitář naklonovat, historii uložit. Dokud klíč platí, platí pro každého, kdo ho má.

K repozitáři zvlášť. Pokud se tajemství dostalo do commitu, GitHub má návod, jak taková data odstranit. Odstranění citlivých dat z repozitáře. Jen mějte na paměti, že úplné vyčištění historie přepisuje už existující commity, a tím se dotkne všech, kdo s repozitářem pracují. Takovou operaci je třeba domluvit s vlastníky, ne ji spouštět na vlastní pěst podle výukového článku. Výměna klíče se dělá hned a s nikým se nedomlouvá.

Co svěřit Claude Code

Agent zvládne skoro celou mechaniku z tohoto článku, až na jednu věc. Samotný tajný klíč zadáváte vy. Rozumné je svěřit mu tohle:

• připravit konfiguraci s názvem proměnné, ne s hodnotou;
• říct, co přesně načítá proměnnou do procesu a ve kterém procesu se má ocitnout;
• zkontrolovat, že tajemství není v klientském buildu ani v souborech, které Git sleduje;
• provést kontrolu přístupu a nahlásit výsledek bez vypsání hodnoty.

Na vás zůstává zadání skutečného klíče mechanismem, který je k tomu určený: skryté zadání v terminálu, lokální soubor, panel hostingu. Do chatu, na snímek obrazovky ani do zprávy agenta se tajemství nedostane nikdy, ani "na vteřinku, jen na kontrolu".

Zadání pro agenta může znít zhruba takto:

Připoj službu přes API. Klíč zadám sám.
Vezmi z dokumentace adresu, metodu a způsob předání klíče.
Do konfigurace dej název proměnné prostředí, ne hodnotu.
Řekni, který proces má proměnnou dostat a co ji načítá.
Zkontroluj, že klíč není v klientském buildu ani v souborech sledovaných Gitem.
Kontrolu přístupu proveď bez výstupu hodnoty a jejích částí.
Nahlás výsledek: nastaveno, není nastaveno nebo přístup zamítnut.

A poslední věc, ke čtení výsledku. "Proměnná je nastavená" a "přístup funguje" jsou dvě různá tvrzení a zaměňovat je nemá smysl. Chybějící hodnota je také něco jiného než odmítnutí ze strany služby. V prvním případě není čím požadavek podepsat, ve druhém služba odpověděla, ale přístup nepovolila. Pokud agent řekne jen "hotovo", upřesněte, co přesně zkontroloval.