---
title: "Управление агентом по API"
id: "2052"
type: "page"
slug: "api"
published_at: "2026-09-28T07:16:38+00:00"
modified_at: "2026-10-06T22:16:44+00:00"
url: "https://pastukhov.com/agents/proxy/docs/api"
markdown_url: "https://pastukhov.com/agents/proxy/docs/api.md"
excerpt: "Иногда удобнее не нажимать кнопки в браузере, а поручить управление программе: другому агенту, вашему скрипту…"
---

# Управление агентом по API

[https://pastukhov.com/agents/proxy/docs/api.md](https://pastukhov.com/agents/proxy/docs/api.md)

Иногда удобнее не нажимать кнопки в браузере, а поручить управление программе: другому агенту, вашему скрипту или системе, которая следит за расходами. Для этого у «Прокси-агента» есть отдельная поверхность по адресу `/api/agent/*`. Через неё можно делать почти всё то же, что администратор в интерфейсе, — и при этом ничего не открывать в браузере.

## Зачем это нужно

Обычно этим пользуются так: агенту передают только адрес вашего сервера и ключ управления, а он сам заводит модели, каналы связи и ключи доступа, а потом читает журналы и расходы. Человеку остаётся проверять результат, а не повторять одни и те же действия руками.

Это удобно и для разовых задач: например, перенести десяток ключей доступа на новый сервер или завести модели по списку из таблицы.

## Ключ управления

Доступ закрыт ключом управления. Ключ передаётся в заголовке `X-API-Key`, а в переменной окружения `PROXY_APP_HASH` хранится не сам ключ, а его необратимая сумма (SHA-256, записанная строчными буквами). По файлу с переменными исходный ключ восстановить нельзя.

- **Переменная не задана** — поверхность отвечает «выключено» (503), и всё остальное на сервере работает как обычно.
- **Ключ не совпал** — ответ «не авторизован» (401).
- **Неудачные попытки** записываются в журнал вместе с адресом обратившегося. Сам ключ и его сумма в журнал не попадают никогда.

Ключ управления стоит держать в секрете: он открывает ровно то же, что и вход администратора, — всю настройку продукта.

## Самопроверка

Отдельной книги по этой поверхности нет — её документация встроена в неё саму. Запрос `GET /api/agent` возвращает описание поверхности: как входить, какие понятия используются, что делается с секретами и полный перечень адресов с полями, ответами и возможными ошибками. Там же — пошаговый рецепт: завести ключ доступа, сделать через него запрос к модели, прочитать журнал.

Поэтому агенту достаточно знать адрес и ключ — остальное он прочитает сам. Список адресов и описание всегда совпадают с тем, что поверхность на самом деле умеет.

## Что можно делать

- **Модели и каналы связи** — создавать, править, копировать, включать и выключать, проверять связь с поставщиком и посмотреть серверы по ссылке на подписку Happ до того, как канал сохранён. Всё то же, что в разделах [Модели и цены](/agents/proxy/docs/models) и [Каналы связи](/agents/proxy/docs/providers) .
- **Ключи доступа** — создавать с пределами расхода, перевыпускать, менять пределы и списки разрешённых моделей и каналов, включать и удалять. Готовый ключ отдаётся ровно один раз.
- **Журналы и аналитика** — читать журнал запросов, журнал прокси-службы и все отчёты аналитики, включая состояние отправки данных в ClickHouse и досыл пропущенных дней.
- **Скрытие секретов** — вести правила, проверять их на примерах «вхолостую» и смотреть отчёты об утечках.
- **Настройки** — читать и записывать значения так же, как [в окне «Настройки»](/agents/proxy/docs/settings) , — результат попадает в те же [файлы конфигурации](/agents/proxy/docs/config) .
- **Состояние** — смотреть статус лицензии и сводку на «Главной».

## Одноразовый код входа в браузер

Иногда программе нужно открыть интерфейс человеку. Пароль администратора для этого не нужен: запрос `POST /api/agent/session` выписывает одноразовый код на 5 минут. Человек вводит его при входе, код срабатывает один раз и выдаёт обычную сессию администратора на 90 дней.

Так агенту не нужно хранить ваш пароль — он лишь выписывает разовый пропуск. После первого использования или по истечении пяти минут код становится недействительным.

## Что остаётся закрытым

Секреты прочитать нельзя ни в интерфейсе, ни по API. Ключи поставщиков, пароли каналов и приватные ключи VPN показываются теми же заглушками, что и в браузере: записать новый секрет можно, прочитать прежний — нет. Готовый ключ доступа показывается один раз при создании или перевыпуске, дальше видны только последние знаки.

Подробнее про то, где лежат секреты, — в разделе [Доступ и безопасность](/agents/proxy/docs/security)
.

## Чего эта поверхность не делает

- **Не заменяет пароль администратора.** Выдать обычный вход в браузер она не может — только разовый код. Сам пароль по-прежнему задаётся переменными окружения.
- **Не открывает секреты.** Ключи и пароли остаются заглушками.
- **Не заменяет лицензию.** Настройку и управление можно вести и без ключа лицензии, но трафик через прокси без него не пойдёт. Сама поверхность лицензией не закрыта.
- **Не смешивается с обычным доступом.** Ключ управления не подойдёт для запросов к моделям, а ключ доступа — для управления.

## Ответы и ошибки

Все запросы синхронные: ответ приходит сразу, долгих операций с ожиданием нет. Проверки связи — быстрые пробы, которые отвечают успехом или неуспехом.

Ошибки приходят единообразно: короткий признак и текст причины. Признаки типовые — ошибка в запросе, объект не найден, противоречие (такое имя уже занято или объект ещё используется). Тексты — на английском: это техническая поверхность для программ, а не раздел для человека.

Дальше: как устроена настройка в файлах — в разделе [Настройки в файлах](/agents/proxy/docs/config)
.

[← Оглавление документации](/agents/proxy/docs)