Як передати ШІ-агенту API-ключ, щоб він не бачив самого ключа?
Дайте агентові посилання, а не ключ, і нехай проксі на тій самій машині підставляє справжній ключ у запит на виході. Ось чому змінні середовища перестали бути достатніми, і як це налаштувати.
Дайте агентові посилання замість ключа, і нехай невеликий проксі на тій самій машині підставляє справжній ключ у запит на виході. Агент записує clavitor://OpenAI/key там, де мав би бути секрет. API отримує справжній ключ. Агент ніколи його не тримає, тож не може його надрукувати, занотувати в журнал або бути вмовлений його віддати.
Це й є вся ідея. Решта цієї сторінки — чому це важливо і як це налаштувати.
Чому «просто покладіть у змінну середовища» перестало бути прийнятним
Рік тому export OPENAI_API_KEY=sk-... був звичайним способом передати ключ скрипту. Ніхто не здивувався.
Потім скрипт почав думати сам.
ШІ-агент читає файли, запускає інструменти, веде журнали й розмовляє з незнайомцями в інтернеті. Кожне з цих — шлях назовні для ключа, який він тримає:
- Середовище. Усе, що запускає агент, його успадковує. Він з'являється в
/proc, у дампах збоїв, у виводі CI. - Пам'ять. Отримайте ключ під час виконання — і він усе одно залишається в процесі, доки працює агент.
- Розмова. Вставлення промпту на вебсторінці або в коментарі до задачі просить агента «додати свою конфігурацію для налагодження». Послужливий агент це робить.
Нічого з цього не потребує помилки в агенті. Потрібно лише, щоб ключ був там, куди агент може дотягнутися.
Патерн: агент просить, проксі підписує
Уявіть картку-ключ у готелі. Гість може відчинити свій номер. Гість ніколи не бачить майстер-ключа, а двері реєструють кожне прикладання.
Для API-ключа це виглядає так:
- Справжній ключ зберігається у сховищі, зашифрований.
- Проксі працює поруч з агентом, на тій самій машині.
- Агент надсилає свій HTTPS-запит із посиланням там, де мав би бути ключ.
- Проксі отримує значення зі сховища, підставляє його в запит і переспрямовує.
- На боці агента лишається лише посилання.
Журнали агента показують посилання. Так само і його вікно контексту. Витікати нічому.
Як налаштувати це з Clavitor
Ось як ми це побудували. Один бінарний файл, одна змінна середовища, жодних змін у коді агента.
Створіть клієнта для агента у своєму сховищі з потрібними йому областями доступу, потім зареєструйте проксі та запустіть його:
$ clavitor-proxy init $ clavitor-proxy ca $ clavitor-proxy serve
init реєструє проксі як цього клієнта. ca виводить центр сертифікації проксі: додайте його до сховища довіри, яким користується HTTP-клієнт вашого агента, бо проксі сам відкриває HTTPS-з'єднання агента. Потім спрямуйте агента на проксі:
$ 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 — це власний токен доступу проксі, файл поруч із бінарним файлом. Кожне з'єднання мусить його містити, тож інший користувач на тій самій машині не зможе скористатися проксі. Проксі слухає на 127.0.0.1:1983 і лише на цій машині, якщо ви навмисно не налаштували його для довіреної приватної мережі.
Це працює з будь-яким агентом, чий HTTP-клієнт враховує HTTPS_PROXY: Claude Code, Codex, ваші власні скрипти. Облікові дані потрапляють лише до хоста, вказаного в його записі як вебадреса, тож агент із вставленим промптом не може спрямувати те саме посилання на сервер незнайомця. Покрокове налаштування описано в документації проксі.
А що з іншими секретами агента?
Не кожен секрет подорожує в HTTP-заголовку. Пароль для розгортання, SSH-ключ, код двофакторної автентифікації для входу.
Для них агент запитує у сховищі по одному іменованому запису за раз через clavitor-cli, і лише ті записи, які йому надані:
$ clavitor-cli get "GitHub Deploy" --field password $ clavitor-cli get "Stripe API" --field key clavitor-cli: CV-2041: Access denied.
Агент не може переглянути список сховища. Пошук за назвою показує щонайбільше п'ять збігів назв, а понад це — лише їхню кількість.
Коди автентифікатора працюють так само. clavitor-cli totp "GitHub" обчислює поточний код на машині агента, тож він може пройти двофакторний вхід, і нікому не треба зазирати в телефон. Сховище тримає секрет зашифрованим.
Чого це не вирішує
Проксі тримає ключ поза агентом. Він не робить агента довіреним.
- Скомпрометований агент усе одно може скористатися наданим йому доступом. Він просто не може забрати ключ із собою.
- Той, хто має адміністративний доступ до машини, теж може скористатися проксі або прочитати його пам'ять.
- API, який повертає ваш ключ у відповіді, віддає його агентові. Проксі підставляє ключі в запити й не фільтрує відповіді.
Тому доступ навколо не менш важливий, ніж сам проксі:
- Область доступу. Кожен агент отримує лише потрібні йому записи. Робочий агент бачить GitHub і AWS. Агент розгортання бачить SSH-ключі та базу даних.
- Ліміти читання. Кожен агент може читати лише певну кількість різних записів за хвилину й за годину, і ці числа встановлюєте Ви. Агент, який двічі протягом двох годин перевищить свій годинний ліміт, блокується, доки Ви його не розблокуєте.
- Журнал. Кожне читання реєструється: який агент, який запис, коли.
Запускаєте кілька агентів? Дайте кожному власний проксі та власну реєстрацію. Тоді кожен має власну область доступу, власні ліміти й власний слід, і агент A не бачить ключів агента B.
Коротко
Не передавайте агентові свій ключ. Передайте йому назву ключа, а сам ключ тримайте на крок позаду, у місці, яке щоразу вирішує, чи може цей агент скористатися ним саме зараз.