Как передать ИИ-агенту API-ключ так, чтобы он его не видел?
Дайте агенту ссылку вместо ключа и позвольте прокси на той же машине подставлять настоящий ключ в запрос на выходе. Почему переменных окружения больше недостаточно и как это настроить.
Дайте агенту ссылку вместо ключа и позвольте небольшому прокси на той же машине подставлять настоящий ключ в запрос на выходе. Агент пишет clavitor://OpenAI/key там, где должен быть секрет. API получает настоящий ключ. Агент никогда его не держит, поэтому не может его напечатать, записать в лог или выдать по уговору.
В этом вся идея. Остальное на этой странице — почему это важно и как это настроить.
Почему «просто положите в переменную окружения» перестало работать
Год назад export OPENAI_API_KEY=sk-... был обычным способом передать ключ скрипту. Никто не удивлялся.
Потом скрипт начал думать сам.
ИИ-агент читает файлы, запускает инструменты, пишет логи и общается с незнакомцами в интернете. Каждое из этого — путь наружу для ключа, который он держит:
- Окружение. Всё, что запускает агент, его наследует. Он виден в
/proc, в дампах падений, в выводе CI. - Память. Получите ключ во время выполнения — и он всё равно лежит в процессе, пока агент работает.
- Разговор. Инъекция промпта на веб-странице или в комментарии к issue просит агента «приложить свою конфигурацию для отладки». Услужливый агент прикладывает.
Ни для чего из этого не нужна ошибка в агенте. Нужен только ключ, лежащий там, куда агент может дотянуться.
Паттерн: агент просит, прокси подписывает
Представьте карточку-ключ отеля. Гость может открыть свой номер. Гость никогда не видит мастер-ключ, а дверь записывает каждое прикладывание.
Для 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.
Коротко
Не передавайте агенту ключ. Передайте ему имя ключа, а сам ключ держите на шаг позади, в месте, которое каждый раз решает, может ли этот агент использовать его прямо сейчас.
Настроить прокси или посмотреть, как работает доступ агентов.