Bir yapay zekâ ajanına, anahtarı görmeden API anahtarı nasıl verilir?
Ajana anahtarı değil bir referans verin ve gerçek anahtarı, istek yola çıkarken aynı makinedeki bir vekil sunucu (proxy) yerleştirsin. Ortam değişkenlerinin neden artık yeterli olmadığını ve kurulumun nasıl yapılacağını anlatıyoruz.
Ajana anahtar yerine bir referans verin ve aynı makinede çalışan küçük bir vekil sunucu, gerçek anahtarı istek yola çıkarken yerleştirsin. Ajan, sırrın geçmesi gereken yere clavitor://OpenAI/key yazar. API gerçek anahtarı alır. Ajan anahtarı hiç elinde tutmaz; dolayısıyla onu yazdıramaz, günlüğe kaydedemez ve onu teslim etmeye ikna edilemez.
Fikir bu kadar. Bu sayfanın geri kalanı, bunun neden önemli olduğunu ve nasıl kurulacağını anlatıyor.
"Ortam değişkenine koy" yaklaşımı neden artık yeterli değil
Bir yıl önce, export OPENAI_API_KEY=sk-... bir anahtarı betiğe vermenin normal yoluydu. Kimse buna itiraz etmiyordu.
Sonra betik kendi kendine düşünmeye başladı.
Bir yapay zekâ ajanı dosyaları okur, araçlar çalıştırır, günlükler yazar ve internetteki yabancılarla konuşur. Bunların her biri, elindeki bir anahtar için bir çıkış yoludur:
- Ortam. Ajanın çalıştırdığı her şey onu devralır.
/prociçinde, çökme dökümlerinde, CI çıktısında görünür. - Bellek. Anahtarı çalışma zamanında çekseniz bile, ajan çalıştığı sürece süreçte durmaya devam eder.
- Konuşma. Bir web sayfasındaki veya bir sorun yorumundaki bir istem enjeksiyonu, ajandan "hata ayıklama için yapılandırmanı eklemesini" ister. Yardımsever bir ajan bunu yapar.
Bunların hiçbiri ajandaki bir hatayı gerektirmez. Yalnızca anahtarın, ajanın erişebileceği bir yerde olmasını gerektirir.
Örüntü: ajan ister, vekil sunucu imzalar
Bir otel anahtar kartı düşünün. Misafir odasını açabilir. Misafir ana anahtarı hiç görmez ve kapı her geçişi günlüğe kaydeder.
Bir API anahtarı için bu şöyle görünür:
- Gerçek anahtar, şifrelenmiş halde bir kasada durur.
- Bir vekil sunucu, ajanın yanında, aynı makinede çalışır.
- Ajan, HTTPS isteğini anahtarın geçeceği yere bir referansla gönderir.
- Vekil sunucu değeri kasadan çeker, isteğe yerleştirir ve iletilir.
- Ajan tarafında yalnızca referans bulunur.
Ajanın günlüklerinde referans görünür. Bağlam penceresinde de öyle. Sızacak bir şey yoktur.
Clavitor ile kurulum
Onu böyle inşa ettik. Tek bir ikili dosya, tek bir ortam değişkeni, ajanın kodunda hiçbir değişiklik yok.
Kasanızda ajan için, ihtiyaç duyduğu kapsamlarla bir istemci oluşturun, ardından vekil sunucuyu kaydedin ve başlatın:
$ clavitor-proxy init $ clavitor-proxy ca $ clavitor-proxy serve
init, vekil sunucuyu o istemci olarak kaydeder. ca, vekil sunucunun sertifika otoritesini yazdırır: ajanın HTTP istemcisinin kullandığı güven deposuna ekleyin, çünkü vekil sunucu ajanın HTTPS bağlantısını kendisi açar. Sonra ajanı vekil sunucuya yönlendirin:
$ export HTTPS_PROXY="http://clavitor:$(cat proxy-auth)@127.0.0.1:1983"
$ curl -H "Authorization: Bearer clavitor://OpenAI/key" \
https://api.openai.com/v1/chat/completionsproxy-auth, vekil sunucunun kendi erişim belirtecidir; ikili dosyanın yanındaki dosyadır. Her bağlantı bunu taşımak zorundadır, böylece aynı makinedeki başka bir kullanıcı vekil sunucuyu ödünç alamaz. Vekil sunucu 127.0.0.1:1983 adresinde ve yalnızca o makinede dinler; güvenilir bir özel ağ için bilerek kurmadığınız sürece.
HTTP istemcisi HTTPS_PROXY değerine uyan her ajanla çalışır: Claude Code, Codex, kendi betikleriniz. Bir kimlik bilgisi yalnızca kaydında web adresi olarak listelenen bir ana makineye gider; böylece istem enjeksiyonuna uğramış bir ajan, aynı referansı bir yabancının sunucusuna yönlendiremez. Adım adım kurulum vekil sunucu belgelerinde yer alır.
Ajanın diğer sırları ne olacak?
Her sır bir HTTP başlığında yolculuk etmez. Bir dağıtım parolası, bir SSH anahtarı, bir oturum açma için iki adımlı doğrulama kodu.
Bunlar için ajan, kasadan clavitor-cli ile her seferinde yalnızca adı belirtilmiş tek bir kaydı ister ve yalnızca kendisine verilmiş kayıtları isteyebilir:
$ clavitor-cli get "GitHub Deploy" --field password $ clavitor-cli get "Stripe API" --field key clavitor-cli: CV-2041: Access denied.
Ajan kasayı listeleyemez. Bir ad araması en fazla beş eşleşen başlık gösterir; daha fazlasıysa yalnızca bir sayı gösterir.
Kimlik doğrulayıcı kodları da aynı şekilde çalışır. clavitor-cli totp "GitHub", güncel kodu ajanın makinesinde hesaplar; böylece iki adımlı bir oturum açmayı, kimsenin telefonu okumadan geçebilir. Kasa, sırrı şifrelenmiş halde tutar.
Bunun çözmediği şeyler
Bir vekil sunucu anahtarı ajanın elinden uzak tutar. Ajanı güvenilir hale getirmez.
- Ele geçirilmiş bir ajan, kendisine verilen erişimi hâlâ kullanabilir. Yalnızca anahtarı evine götüremez.
- Makinede yönetici erişimi olan biri vekil sunucuyu da kullanabilir veya belleğini okuyabilir.
- Yanıtınızda anahtarınızı geri yankılayan bir API, onu ajana teslim eder. Vekil sunucu anahtarları isteklere yerleştirir ve yanıtları filtrelemez.
Bu yüzden etrafındaki erişim, vekil sunucu kadar önemlidir:
- Kapsam. Her ajan yalnızca ihtiyaç duyduğu kayıtları alır. Bir iş ajanı GitHub ve AWS görür. Bir dağıtım ajanı SSH anahtarlarını ve veritabanını görür.
- Okuma sınırları. Her ajan, dakikada ve saatte yalnızca belirli sayıda farklı kayıt okuyabilir; sayıları siz belirlersiniz. İki saat içinde iki kez saatlik sınırını aşan bir ajan, siz kilidini açana kadar kilitlenir.
- Bir kayıt. Her okuma günlüğe yazılır: hangi ajan, hangi kayıt, ne zaman.
Birkaç ajan mı çalıştırıyorsunuz? Her birine kendi vekil sunucusunu ve kendi kaydını verin. Böylece her birinin kendi kapsamı, kendi sınırları ve kendi izi olur; A ajanı, B ajanının anahtarlarını göremez.
Kısa versiyon
Ajanınıza anahtarınızı vermeyin. Ona anahtarın bir adını verin ve anahtarı bir adım ötede, her seferinde bu ajanın şu anda onu kullanıp kullanamayacağına karar veren bir yerde tutun.
Vekil sunucuyu kurun veya ajan erişiminin nasıl çalıştığını görün.