Bagaimana saya memberikan API key ke agen AI tanpa agen tersebut melihat key-nya?
Beri agen sebuah referensi, bukan key-nya, dan biarkan proxy di mesin yang sama menyisipkan key yang sebenarnya ke dalam permintaan saat keluar. Berikut alasan mengapa env var tidak lagi cukup, dan cara menyiapkannya.
Beri agen sebuah referensi alih-alih key-nya, dan biarkan proxy kecil di mesin yang sama menukar key yang sebenarnya ke dalam permintaan saat keluar. Agen menulis clavitor://OpenAI/key di tempat rahasia itu seharusnya berada. API menerima key yang sebenarnya. Agen tidak pernah memegangnya, sehingga agen tidak bisa mencetaknya, mencatatnya dalam log, atau dibujuk untuk menyerahkannya.
Itulah seluruh idenya. Sisa halaman ini menjelaskan mengapa hal itu penting, dan cara menyiapkannya.
Mengapa "taruh saja di env var" tidak lagi memadai
Setahun yang lalu, export OPENAI_API_KEY=sk-... adalah cara normal untuk memberikan key kepada sebuah skrip. Tidak ada yang keberatan.
Lalu skrip itu mulai berpikir sendiri.
Sebuah agen AI membaca file, menjalankan tool, menulis log, dan berbicara dengan orang asing di internet. Setiap salah satu dari itu adalah jalan keluar bagi key yang dipegangnya:
- Environment. Apa pun yang dijalankan agen mewarisinya. Key itu muncul di
/proc, dalam crash dump, dalam output CI. - Memori. Ambil key saat runtime dan key itu tetap berada di proses selama agen berjalan.
- Percakapan. Prompt injection di sebuah halaman web atau komentar issue meminta agen untuk "menyertakan konfigurasi Anda untuk debugging". Agen yang suka membantu akan melakukannya.
Semua itu tidak memerlukan bug pada agen. Yang diperlukan hanyalah key berada di suatu tempat yang dapat dijangkau agen.
Polanya: agen meminta, proxy menandatangani
Bayangkan kartu kunci hotel. Tamu dapat membuka kamarnya. Tamu tidak pernah melihat master key, dan pintu mencatat setiap gesekan kartu.
Untuk API key, polanya seperti ini:
- Key yang sebenarnya disimpan di brankas, terenkripsi.
- Proxy berjalan di samping agen, di mesin yang sama.
- Agen mengirim permintaan HTTPS-nya dengan referensi di tempat key seharusnya berada.
- Proxy mengambil nilai dari brankas, menyisipkannya ke dalam permintaan, lalu meneruskannya.
- Sisi agen hanya pernah memegang referensi.
Log agen menampilkan referensi. Context window-nya juga. Tidak ada yang bisa bocor.
Cara menyiapkannya dengan Clavitor
Beginilah cara kami membangunnya. Satu binary, satu variabel environment, tanpa perubahan pada kode agen.
Buat client untuk agen di brankas Anda dengan scope yang dibutuhkannya, lalu daftarkan proxy dan jalankan:
$ clavitor-proxy init $ clavitor-proxy ca $ clavitor-proxy serve
init mendaftarkan proxy sebagai client tersebut. ca mencetak certificate authority milik proxy: tambahkan ke trust store yang digunakan HTTP client agen Anda, karena proxy membuka koneksi HTTPS agen itu sendiri. Kemudian arahkan agen ke proxy:
$ 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 adalah access token milik proxy itu sendiri, file di samping binary. Setiap koneksi harus membawanya, sehingga pengguna lain di mesin yang sama tidak bisa meminjam proxy. Proxy mendengarkan di 127.0.0.1:1983 dan hanya di mesin itu, kecuali Anda sengaja menyiapkannya untuk jaringan privat tepercaya.
Ini bekerja dengan agen apa pun yang HTTP client-nya menghormati HTTPS_PROXY: Claude Code, Codex, skrip Anda sendiri. Sebuah kredensial hanya dikirim ke host yang tercantum sebagai alamat web pada entrinya, sehingga agen yang terkena prompt injection tidak bisa mengarahkan referensi yang sama ke server orang asing. Panduan langkah demi langkah ada di dokumentasi proxy.
Bagaimana dengan rahasia lain milik agen?
Tidak semua rahasia berpindah lewat HTTP header. Kata sandi deploy, SSH key, kode dua faktor untuk sign-in.
Untuk itu, agen meminta brankas satu entri bernama pada satu waktu dengan clavitor-cli, dan hanya untuk entri yang diberikan kepadanya:
$ clavitor-cli get "GitHub Deploy" --field password $ clavitor-cli get "Stripe API" --field key clavitor-cli: CV-2041: Access denied.
Agen tidak bisa mendaftar isi brankas. Pencarian nama menampilkan paling banyak lima judul yang cocok, dan hanya berupa jumlah di atas itu.
Kode authenticator bekerja dengan cara yang sama. clavitor-cli totp "GitHub" menghitung kode saat ini di mesin agen, sehingga agen dapat melewati sign-in dua faktor tanpa ada yang membaca ponsel. Brankas menyimpan rahasianya dalam bentuk terenkripsi.
Apa yang tidak diselesaikan oleh ini
Proxy menjauhkan key dari agen. Proxy tidak membuat agen menjadi tepercaya.
- Agen yang terkompromi tetap dapat menggunakan akses yang diberikan kepadanya. Agen hanya tidak bisa membawa pulang key-nya.
- Seseorang dengan akses administrator ke mesin juga dapat menggunakan proxy, atau membaca memorinya.
- API yang menggemakan key Anda kembali dalam responsnya menyerahkannya kepada agen. Proxy menyisipkan key ke dalam permintaan dan tidak memfilter respons.
Itulah mengapa akses di sekitarnya sama pentingnya dengan proxy-nya:
- Scope. Setiap agen hanya mendapat entri yang dibutuhkannya. Agen kerja melihat GitHub dan AWS. Agen deploy melihat SSH key dan database.
- Batasan baca. Setiap agen hanya boleh membaca sejumlah entri berbeda per menit dan per jam, dan Anda yang menentukan angkanya. Agen yang melampaui batas per jamnya dua kali dalam dua jam dikunci sampai Anda membukanya.
- Catatan. Setiap pembacaan dicatat dalam log: agen mana, entri mana, kapan.
Menjalankan beberapa agen? Beri masing-masing proxy dan pendaftarannya sendiri. Dengan begitu masing-masing memiliki scope, batasan, dan jejaknya sendiri, dan agen A tidak bisa melihat key milik agen B.
Versi singkatnya
Jangan serahkan key Anda kepada agen. Serahkan sebuah nama untuk key itu, dan simpan key-nya satu langkah lebih jauh, di tempat yang memutuskan, setiap kali, apakah agen ini boleh menggunakannya sekarang.