API Anahtarları ve Ortam Değişkenleri

Bağlantı neredeyse hazır. Ajan yapılandırmayı oluşturdu, hizmeti adlandırdı ve bir alanda durdu - API anahtarı. Hizmet uzun bir dize verdi, ama dizeye bakarak nereye konacağı anlaşılmıyor. Sohbete mi? Kodun yanındaki bir dosyaya mı? Kesin çalışsın diye doğrudan yapılandırmaya mı?

Bunu tek bir modelle anlatalım. Değerin nerede ayarlandığını, hangi sürecin onu aldığını ve sırrı göstermeden her şeyin ayarlı olduğundan nasıl emin olacağınızı göreceğiz. Model yerel çalıştırma, MCP bağlantısı ve yayınlanan uygulama için aynıdır; değişen tek şey, kimin ortamını ayarladığımızdır.

API Anahtarı Ne Sağlar?

Anahtar bir isteği bir hesapla ya da projeyle ve size verilen izinlerle ilişkilendirir. Hizmet ona bakarak isteği kimin gönderdiğini, bu kişinin neler yapabileceğini ve şimdiye kadar ne kadar istekte bulunduğunu anlar. Anahtarın tam olarak ne anlama geldiğini her hizmet kendisi belirler. Bazılarında bu tüm hesaba erişimdir, bazılarında yalnızca tek bir projeye ve yalnızca okuma erişimi.

Talimatlarda "anahtar" kelimesinin yanında token da geçer. Gündelik metinlerde ikisi çoğu zaman aynı anlamda kullanılır, ama mekanizmanın ayrıntıları farklıdır: nasıl alındıkları, ne kadar geçerli oldukları ve hangi izinleri kapsadıkları. Bunları tam eş anlamlı saymamak daha iyi - hizmetin tam olarak ne verdiği kendi belgelerinde yazar.

Hizmetin sizi neden ayırt etmesi gerektiğini gündelik bir örnekte görmek daha kolay. Bir hesap açtınız, aylık istek limiti olan bir plan seçtiniz ve bir anahtar aldınız. Bundan sonra hizmet bu anahtara bakarak isteklerinizi sayar, limitle karşılaştırır ve plan ücretliyse fatura keser. Anahtar yabancıların eline geçerse, limitinizi de faturanızı da başkası kullanmaya başlar.

Anahtar kendi başına karar vermez. Hizmete yalnızca sahibin ayarlarına giden bir referans verir; bu isteğe izin verilip verilmeyeceğine ve limitten düşülüp düşülmeyeceğine hizmetin kendisi karar verir.

Hizmetin özellikle herkese açık diye işaretlediği değerler de vardır; sayfa koduna konması gerekenler tam da bunlardır. Herkese açık bir değeri gizli bir değerden değişkenin adına bakarak ayırt edemezsiniz. Değerin ne için olduğu belgelerde yazar, bakılacak yer orası. Aşağıdaki örneklerin hepsinde fc-EXAMPLE-0000000000 gibi bariz yer tutucular var, gerçek bir anahtar böyle görünmez.

Uygulama Sırrı Nerede Saklayabilir?

Şöyle bir durum düşünün. Anahtarı doğrudan sayfa koduna eklediniz, projeyi çalıştırdınız ve API'den yanıt aldınız. Her şey çalışıyor. Yayından sonra da uygulama açılıyor, istekler geçiyor - iş bitmiş gibi görünüyor.

Ama kodla birlikte anahtar da her ziyaretçinin tarayıcısına gider. Geliştirici araçlarını açmak, anahtarı JavaScript'te ya da istekte bulmak ve kopyalamak yeterli. Bundan sonra o kişi sizin adınıza kendi isteklerini gönderebilir. Bu istekler, hizmet artık sizin isteklerinizi reddetmeye başlayana kadar limitinizi tüketir.

Sorun belirli bir derleme aracında değil. Sayfanın tarayıcıya gönderdiği her şey, o tarayıcının sahibinin erişimindedir: HTML, stiller, JavaScript, isteklerin adresleri ve başlıkları. Derleme sırasında anahtar yerel .env dosyasından alınmış olsa bile, JavaScript'e yerleştirildikten sonra kodun geri kalanıyla birlikte ziyaretçiye gider.

Backend, sunucuda çalışan koddur. Ziyaretçi onun yanıtlarını alır, ama kaynak kodunu ve sunucu sürecinin ortam değişkenlerini almaz. Bu yüzden backend anahtarı kendi tarafında tutabilir ve harici hizmete uygulama adına erişebilir.

İsteğin akışı değişir. Tarayıcı backend'inize gizli anahtar içermeyen sıradan bir istek gönderir. Backend anahtarı kendi ortamından okur, API'ye giden ayrı bir isteğe ekler ve tarayıcıya yalnızca sonucu döndürür.

Artık ziyaretçi backend'in adresini ve yanıttaki verileri görür, ama harici hizmetin anahtarını görmez. Sır, onu kullanan süreçte kalır.

Sırrın iki olası sahibi vardır:

• yerel süreç - entegrasyon bağlanmış Claude Code, bir betik ya da geliştirme sunucusu. Bilgisayarınızda çalışır ve anahtarı da orada alır;
• yayınlanan uygulamanın backend'i - harici API'ye kendisi erişen, sunucudaki kod. Ortamı barındırma panelinde ayarlanır.

Bunlar iki ayrı ayardır. Hizmet ve değişken adı aynı olsa bile, bilgisayarınızın ortamındaki anahtar barındırma tarafında kendiliğinden ortaya çıkmaz.

Anahtarı backend'e taşımak onu tarayıcıdan gizler, ama herkese açık bir backend'i de yabancı isteklerden korumak gerekir.

Ortam Değişkeni Nasıl Çalışır?

Ortam değişkeni, bir programın başlatılırken aldığı, adı olan bir değerdir. Bir adı vardır, örneğin FIRECRAWL_API_KEY, bir de değeri - o uzun dize. Yapılandırmalara ve koda ad yazılır; değer ayrı durur ve kodun yanında saklanmaz.

Program bu değeri nereden alır? Terminalden başlatılan bir program o terminalin ortamını devralır. Bir pencerede değişkeni ayarladınız, Claude Code'u o pencereden başlattınız - Claude Code değişkeni görür. İkinci bir pencere açıp değişkeni orada ayarladınız - zaten çalışan süreci bu etkilemez, o ortamını başlarken aldı.

"Anahtar ayarlı ama çalışmıyor" şikayetinin en sık nedeni de buradan çıkar. Değer yanlış pencerede ya da süreç başladıktan sonra ayarlanmıştır. Çözüm, süreci değişkenin bulunduğu terminalden yeniden başlatmaktır.

Açıkça sahte bir değerle öğretici bir örnek:

# bash: mevcut terminal için değişken
export FIRECRAWL_API_KEY=fc-EXAMPLE-0000000000

# PowerShell: aynı şey
$env:FIRECRAWL_API_KEY = "fc-EXAMPLE-0000000000"

Öğretici örnekte, yer tutucuyla böyle yazmakta sakınca yok. Gerçek bir anahtarı bu şekilde yazmamak gerekir. Dizenin tamamı komut geçmişine kaydedilir ve terminali kapattıktan sonra da orada kalır. Gerçek değer için yankısız giriş vardır - dizeyi yapıştırırsınız, ekranda hiçbir şey görünmez ve geçmişe yalnızca komutun kendisi girer:

# bash: değer gizli olarak girilir
read -s -r FIRECRAWL_API_KEY
export FIRECRAWL_API_KEY

# PowerShell: gizli giriş ve değerin ortam değişkenine açılması
$secure = Read-Host "FIRECRAWL_API_KEY" -AsSecureString
$env:FIRECRAWL_API_KEY = [System.Net.NetworkCredential]::new('', $secure).Password

Ayarı, değer ekrana, loglara ya da bir ekran görüntüsüne düşmeyecek şekilde kontrol etmek gerekir. "Ayarlı mı, değil mi" sorusunu yanıtlamak için iki satır yeterli:

# bash
[ -n "$FIRECRAWL_API_KEY" ] && echo "ayarlanmış" || echo "ayarlanmamış"

# PowerShell
if ($env:FIRECRAWL_API_KEY) { "ayarlanmış" } else { "ayarlanmamış" }

Ne uzunluğu ne de ilk karakterleri yazdırmaya gerek var. Kontrole bir şey katmaz, üstelik anahtarın bir parçası da zaten sırrın bir parçasıdır.

Bir değişkeni kalıcı olarak ayarlamanın birçok yolu var ve her sistemde farklılar. Şu an bunlarla uğraşmanıza gerek yok: yerel çalışma için terminal yeterli, barındırmada ise değişkenler barındırmanın kendi panelinde ayarlanır.

.env ve .env.example Neden Gerekli?

Her yeni terminalde değişkenleri elle ayarlamak çabuk bıktırır, bu yüzden değerler .env adlı bir metin dosyasına konur. Dosyadaki her satır bir ad-değer çifti tutar.

En sık atlanan önemli bir ayrıntı var. Dosyanın kendisi hiçbir şeyi ayarlamaz. Birinin onu okuyup değerleri sürecin ortamına yerleştirmesi gerekir - uygulamanın, bir kütüphanenin ya da programınızı başlatan launcher'ın. .env oluşturup artık her programın onu okuyacağını varsaymak olmaz. Sizin durumunuzda dosyayı tam olarak neyin yüklediğini tahmin etmek yerine açıkça öğrenmek gerekir.

Yanında genellikle iki dosya daha vardır:

# .env - sadece sizin makinenizde kalır
FIRECRAWL_API_KEY=fc-EXAMPLE-0000000000

# .env.example - projeyi açacaklar için şablon
# değerler boş, burada sadece adlar
FIRECRAWL_API_KEY=

# .gitignore
.env

Bu ayrımın mantığı basit. .env.example "bu projenin hangi değişkenlere ihtiyacı var" sorusunu yanıtlar ve içinde değer olmadığı için depoda rahatça durabilir. Gerçek anahtarlar geçici olarak bile bu dosyaya taşınmaz.

Git'i henüz bilmiyorsanız, burada .gitignore dosyasının rolünü akılda tutmanız yeterli. Depoya eklenmemesi gereken dosyaları listeler. Git ile ve .gitignore ile çalışmayı 13. seviyede ayrıntılı olarak ele alacağız.

Şimdi de .gitignore ile ilgili, sık sık içine düşülen bir tuzak. Kural yalnızca Git'in henüz izlemediği dosyalara uygulanır. .env bir kez commit'lendiyse, .gitignore dosyasına satır eklemek onu takipten çıkarmaz. Dosya sürüm kontrolünde kalır ve değişiklikleri commit'lere girmeye devam eder. Git belgelerinde bu açıkça yazıyor: Git'in zaten izlediği dosyalar yok sayma kurallarından etkilenmez. gitignore Belgeleri.

Şemada asıl koşul ortada duruyor. .gitignore içindeki aynı satır, yalnızca .env izlenmediği sürece işe yarar. Zaten izlenen bir dosya için ayrı bir adım gerekir.

Bu yüzden dosyaya gerçek bir sır yazmadan önce Git'in ondan haberi olmadığından emin olmakta fayda var. git status, dosyanın değişikliklerde görünüp görünmediğini gösterir. Dosya zaten izleniyorsa, git rm --cached .env komutuyla takipten çıkarılır ve bu değişiklik commit'lenir - dosya diskte kalır, ama sürüm kontrolünden çıkar.

Yalnız bunun sadece gelecekteki commit'leri etkilediğini unutmayın. Geçmişe zaten girmiş bir değer orada kalır ve onunla başka türlü ilgilenmek gerekir - bu konu aşağıda.

Anahtar MCP Bağlantısına Nasıl İletilir?

MCP, harici bir aracı Claude Code'a bağlamanın bir yoludur. Bağlantı .mcp.json dosyasında tanımlanır ve bu dosya genellikle depoda, projenin yanında durur, yani tüm ekip onu görür. Demek ki içinde sır olmamalı.

Firecrawl hizmetinin HTTP üzerinden en basit bağlantısı şöyle görünür:

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

Dosyada anahtar yok. Başlıkta ${FIRECRAWL_API_KEY} duruyor - ortam değişkenine adıyla yapılan bir referans. Claude Code buraya, içinde çalıştığı sürecin ortamındaki değeri yerleştirir. Depoya ad gider, değer ise herkeste kendine ait kalır. Claude Code bu yerleştirmeyi url, headers, env, command ve args alanlarında yapabilir. Claude Code ve MCP.

Şemada, istek başlığında farklı yerlerden gelen iki şeyin buluştuğu görülüyor. Başlık şablonu ortak yapılandırmadan gelir, değer ise sürecin ortamından yerleştirilir. Hiçbir adımda anahtar, depoya giden bir dosyaya yazılmaz.

Adresi ve anahtarın iletilme şeklini hizmetin kendi belgelerinden alırsınız. Firecrawl'da bu Authorization başlığıdır ve belgeler anahtarın MCP adresine konmamasını ayrıca rica eder. Nedeni basit. Adres sıradan bir metindir; yapılandırmaya, loglara ve komut geçmişine girer, anahtar da onunla birlikte oralara gider.

Bazı hizmetler tarayıcı üzerinden girişi destekler. İstemci giriş sayfasını kendisi açar ve API anahtarını elle iletmeniz hiç gerekmez. Firecrawl bunun için ayrı bir adres sunuyor. Firecrawl MCP Belgeleri.

Araç yanıt vermiyorsa, sırayla şunları kontrol edin:

1. yapılandırmadaki değişken adı ile sizin ayarladığınız ad son karakterine kadar aynı mı;
2. değer, Claude Code'un başlatıldığı süreçte ayarlanmış mı;
3. süreç, değişken ayarlandıktan sonra yeniden başlatılmış mı.

Değişken yoksa Claude Code sessizce çökmez. Yapılandırmayı yükler, ${FIRECRAWL_API_KEY} metnini yerine bir şey koymadan bırakır ve eksik değişkenin adını içeren bir uyarı yazar. Değerin kendisi hiçbir yerde yazdırılmaz, yani bu teşhis güvenlidir. Sorunu bulmak için tüm ortamı ekrana dökmenize kesinlikle gerek yok.

Anahtar Zaten Dışarı Sızdıysa

Bu sık rastlanan bir durum. Anahtar bir mesaja, bir commit'e ya da bir ekran görüntüsüne düşmüş. Paniğe gerek yok, ama ertelemek de doğru olmaz. İzlenecek sıra şu:

1. anahtarı hizmetin hesap panelinde iptal edin ya da yenisiyle değiştirin. Eski dizenin artık hiçbir kapıyı açmamasını sağlayan tek adım budur;
2. yeni değeri gereken yerlerde ayarlayın: yerelde, barındırmada, bağlantı ayarlarında;
3. anahtarın yayıldığı yerle ilgilenin - mesajı silin, dosyayı düzeltin, erişimi kapatın;
4. hesap panelinde anahtarın nasıl kullanıldığına ve hizmetin harcamalar için ne gösterdiğine bakın.

Sıra tam olarak böyle ve ilk adımın yeri değişmez. Silinmiş bir mesaj ya da eskisinin üstüne atılan yeni bir commit, önceki sırrı güvenli hale getirmez. Mesaj okunmuş, depo klonlanmış, geçmiş kaydedilmiş olabilir. Anahtar geçerli olduğu sürece, elinde bulunduran herkes için geçerlidir.

Depo konusu ayrı. Sır bir commit'e girdiyse, GitHub'ın bu tür verilerin kaldırılmasıyla ilgili bir kılavuzu var. Depodan Hassas Verileri Kaldırma. Yalnız şunu bilin: geçmişin tamamen temizlenmesi var olan commit'leri yeniden yazar ve dolayısıyla bu depoyla çalışan herkesi etkiler. Böyle bir işlem depo sahipleriyle birlikte kararlaştırılır, bir eğitim makalesine bakarak tek başına başlatılmaz. Anahtarın değiştirilmesi ise hemen yapılır ve kimseyle kararlaştırılmaz.

Claude Code'a Neler Bırakılabilir?

Ajan bu makaledeki mekaniğin neredeyse tamamını üstlenebilir, bir şey hariç: sırrın kendisini siz girersiniz. Ona şunları bırakmak mantıklı:

• değeri değil, değişkenin adını içeren bir yapılandırma hazırlamak;
• değişkeni sürece neyin yüklediğini ve değişkenin hangi süreçte olması gerektiğini söylemek;
• sırrın istemci derlemesinde ve Git'in izlediği dosyalarda olmadığını kontrol etmek;
• erişim kontrolünü yapmak ve değeri yazdırmadan sonucu bildirmek.

Gerçek anahtarı bunun için öngörülen yolla girmek size kalıyor: terminalde gizli giriş, yerel dosya, barındırma paneli. Sır hiçbir zaman sohbete, ekran görüntüsüne ya da ajanın raporuna girmez, "bir saniyeliğine, kontrol etmek için" bile.

Görev tanımı kabaca şöyle olabilir:

Hizmeti API üzerinden bağla. Anahtarı kendim ayarlayacağım.
Adresi, yöntemi ve anahtarın iletilme şeklini belgelerden al.
Yapılandırmaya değeri değil, ortam değişkeninin adını koy.
Değişkeni hangi sürecin alması gerektiğini ve onu neyin yüklediğini söyle.
Anahtarın istemci derlemesinde ve Git'in izlediği dosyalarda olmadığını kontrol et.
Erişim kontrolünü değeri ve parçalarını yazdırmadan yap.
Sonucu bildir: ayarlandı, ayarlanmadı ya da erişim reddedildi.

Son olarak raporun okunması hakkında. "Değişken ayarlı" ile "erişim çalışıyor" farklı iddialardır, birini diğerinin yerine koymamak gerekir. Değerin olmaması da hizmetin reddetmesinden farklıdır. İlkinde isteği imzalayacak bir şey yoktur, ikincisinde hizmet yanıt vermiş ama erişim tanımamıştır. Ajan yalnızca "hazır" diyorsa, tam olarak neyi kontrol ettiğini sorun.