mistgate Документация
RU
300

В админке: ИИ

MCP-сервер

Встроенный MCP-сервер панели для ИИ-агентов, как подключить клиент, все инструменты, схема «план → применить» и какие изменения ждут владельца.

На этой странице

В панель встроен сервер Model Context Protocol (MCP), чтобы ИИ-агент мог смотреть на флот и делать повседневные изменения. Он использует те же API-токены и те же процедуры, что и API админки: что агент видит и может, решает профиль токена, а каждый вызов попадает в журнал аудита. За один вызов ничего не меняется: агент сначала планирует изменение, затем применяет его, а самые рискованные изменения ждут одобрения владельца в админке.

Описанный ниже HTTP-эндпоинт доступен в VPS-редакции. В edge-варианте /mcp на этапе 1 не обслуживается; поддержку Edge планируют добавить на этапе 2 через service binding к отдельному Worker.

Адрес#

Текст
<адрес админки>mcp
https://panel.example.com/<prefix>/mcp
  • Streamable HTTP, без состояния, ответы в JSON. Только инструменты: ни ресурсов, ни промптов, ни sampling.
  • Адрес есть только на стороне админки (секретный префикс, хост или отдельный адрес) и никогда — на публичной стороне.
  • Каждому запросу нужен Authorization: Bearer tk1_…, и каждый проверяется заново: отозванный или истёкший токен останавливается на следующем же запросе. Сессии, которую можно перехватить, нет.
  • tools/list показывает только инструменты, разрешённые профилю токена.

ИИ → MCP и токены показывает адрес и готовый фрагмент настройки для каждого вида клиента.

Подключение клиента#

Создайте токен в ИИ → MCP и токены с самым узким профилем, которого хватает (см. профили токенов). Затем:

Claude Code (Streamable HTTP):

Shell
claude mcp add --transport http mistgate https://panel.example.com/<prefix>/mcp --header "Authorization: Bearer <token>"

Любой клиент со Streamable HTTP:

JSON
{
  "mcpServers": {
    "mistgate": {
      "type": "http",
      "url": "https://panel.example.com/<prefix>/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Клиенты, которые умеют только запускать команду (например, Claude Desktop), используют stdio-прокси mistgate mcp на вашем компьютере. Сохраните токен первой строкой файла, который читаете только вы, затем:

JSON
{
  "mcpServers": {
    "mistgate": {
      "command": "mistgate",
      "args": ["mcp", "--url", "https://panel.example.com/<prefix>/", "--token-file", "<path-to-token-file>"]
    }
  }
}

stdio-прокси#

mistgate mcp --url <адрес админки> --token-file <файл> запускает локальный MCP-сервер на stdin и stdout и пересылает каждое сообщение в панель. Сам он ничего не решает, ничего не кеширует и не знает ни одного инструмента: отвечает панель.

  • Токен читается только из первой строки файла, никогда из командной строки или окружения, и никогда не печатается. Если файл читают другие, печатается предупреждение (в Windows это не проверяется).
  • --url должен быть https, кроме localhost и loopback-адресов. Перенаправления не выполняются, так что токен никуда больше не уйдёт.
  • Когда панель отклоняет токен (истёк, отозван или не тот профиль), прокси останавливается с этим сообщением.
  • Запасные переменные для --url и --token-file — MISTGATE_URL и MISTGATE_TOKEN_FILE.

mistgate собирается под Linux, macOS и Windows: go build ./cmd/mistgate соберёт бинарник для компьютера, на котором работает агент. См. CLI.

Ограничения#

Ограничение Значение
Одновременных вызовов инструментов на токен 4 (больше — 429 «at most 4 tool calls at a time per token»)
Запросов в минуту собственный лимит токена
Тело запроса 3 МиБ
Результат инструмента 32 КиБ; длинные списки уменьшаются вдвое, пока не поместятся, и помечаются как урезанные
Время на вызов 30 секунд на чтение и план, 90 секунд на применение
Открытых планов 20 на токен; 50 ожидающих владельца на всю панель
Сохранённые аргументы плана 8 КиБ (3 МиБ для загрузки сайта-ширмы)

Инструменты#

Инструменты чтения#

Инструменты чтения ничего не меняют. Аргументы — идентификаторы и простые слова, никогда не URL: ни один инструмент не загружает то, что назвал агент. Ноду можно указать идентификатором или точным именем. Столбец «Профиль» — самый младший профиль, который видит инструмент; старшие профили видят его тоже.

Инструмент Профиль Что возвращает
fleet_status Только чтение Все ноды со статусом, причиной, людьми онлайн, скоростью и CPU; итоги, число алертов и главных потребителей сейчас.
fleet_digest Только чтение Проблемы флота одним вызовом: hours (от 1 до 72, по умолчанию 24); всё считается только внутри этого окна. В problem_nodes у каждой ноды список причин (code, count, last_at): простои и всплески с длительностью (minutes и minutes_in_window, обрезанные по окну), алерты, открытые в окне или всё ещё открытые, по видам, предупреждения и ошибки журнала по источникам, проваленные раунды проверок, path_lossy и другие предупреждения, смены вердикта по стране, сбои и откаты обновлений и то, что нода сейчас не в сети. quiet_nodes перечисляет остальные. В totals итоги флота; traffic_hourly и online_hourly — почасовые ряды, которых нет в fleet_status, а у проблемных нод есть spark_bytes_24h. История проверок почасовая, поэтому считаются корзины, пересекающие окно. unavailable называет часть, которую не удалось прочитать.
user_diagnose Только чтение Почему человек не может подключиться, одним вызовом: user_id и необязательный hours (от 1 до 168, по умолчанию 24). Пользователь и его доступ (статус, срок, квота, лимит и список устройств), ноды и профили, которые даёт его подписка (только структура, как в subscription_preview), по устройству и ноде вердикт соединений по счётчикам (ok, rejected, unanswered, answers_lost, stalled, throttled, frozen, lossy, slow, no_attempts) с signals, алерты и события о человеке, состояние его нод (статус, вердикт по стране, сбои проверок) и короткий машиночитаемый список findings (device_limit_reached, expired, disabled, over_quota, never_connected, no_attempts_in_window, rejects_auth, handshake_unanswered (AmneziaWG: нода не отвечает, наша сторона), handshake_answers_lost (нода отвечает, а ответы не доходят: обратный путь перерезан), stalls, tcp_freeze_16k (соединения VLESS встают после первых 8–32 КиБ: TCP-троттлинг), freezes, high_loss, high_rtt, node_down, node_blocked_in_country, no_node_access, no_profiles, device_blocked, no_counters) с severity, ссылками evidence и detail; verdict — самая серьёзная находка. С агентами links/3 у соединения есть ещё tcp_stalls, tcp_stalls_16k, initiations, responses и responses_unmatched, а not_known называет те из них, которые нода сказать не может (старый агент, бэкенд AWG в ядре). Только числа: ни ключей, ни ссылок, ни пароля страницы, ни адресов клиентов.
timeline Только чтение Что произошло, сначала новое, одним нормализованным списком {at, kind, severity, code, node, subject, summary_key, params, ref} из событий, моментов открытия и закрытия алертов, журнала нод (одна запись на ноду, источник и час), перезапусков агента (restart), раскаток и, только для профиля admin, журнала аудита (без адресов). node или user сужают выборку; окно задают hours (от 1 до 168, по умолчанию 24) или from и to (unix-секунды); фильтры — kinds, min_severity и changes_only (аудит, раскатки, события state_applied, профилей, ретрансляторов, настроек и обновлений). limit (по умолчанию 50, не больше 100) и next_cursor обходят все источники в одном порядке. partial_sources называет источник, упёршийся в предел чтения.
node_get Только чтение Одна нода: статус и причина, данные хоста, входящие подключения с состоянием, direct_in_subscriptions (попадает ли адрес ноды в подписку) и cdn (подключаются ли клиенты через CDN-хост), до 10 людей онлайн, заметки владельца и ipv6: включён ли его вход по IPv6, может ли нода его принять (unavailable_reason: no_ipv6, ipv6_broken, agent_old, not_checked или main_is_ipv6) и последняя проверка адреса. Без адресов, ключей и отпечатков сертификатов.
nodes_get Только чтение node_get для многих узлов одним вызовом: nodes — список id или точных имён узлов, пусто = каждый узел, кроме выведенных (не больше 50). Если ответ слишком велик, сначала уходят пользователи онлайн, затем целые узлы, и ставится truncated.
warp_status Только чтение Есть ли у ноды WARP-аккаунт и включён он или на паузе; состояние агента, colo, возраст рукопожатия, статус и задержка проверок Cloudflare и другого сайта, время регистрации, наличие токена для обновления аккаунта и профили с выходом через WARP. Без адресов, ключей, идентификатора аккаунта, лицензии и токенов. Без node: такая же краткая строка для каждого узла, кроме выведенных (unavailable называет узлы, которые не ответили).
relays_list Только чтение Ретрансляции: порты на ноде входа, которые пересылают сервер ноды выхода как есть. Необязательный node оставляет те, где она на любом конце. По каждой: ноды входа и выхода, сервер выхода (профиль, протокол, сеть), порт на входе и на выходе, enabled, state (pending, active, failed; last_error_code — первое слово ошибки агента), exit_live, agent_supported и last_check: плечо (вход достаёт до сервера выхода) и путь (третья нода достаёт до него через вход), каждое — ok, fail или skipped с кодом, нодой, отправившей пробу, и для UDP числом отправленных и посчитанных пакетов. Сохранённые данные, ноды не опрашиваются. Без адресов.
relay_candidates Только чтение Для ноды входа (node): серверы других нод, которые она могла бы ретранслировать. По каждому: inbound_id (его принимает relay_plan), нода выхода, профиль, протокол, сеть и порт; unsupported (cdn, acme_ip, build_failed; пусто — можно ретранслировать; сервер AmneziaWG можно); hop (у сервера диапазон hop, ретрансляция передаёт один порт); relay_id (этот вход уже его ретранслирует); exit_country_check (как страновая проверка видит выход: ok, partial, blocked, listed или no_data, и сети, где он недоступен); entry_reaches_exit (reach, partial, blocked или no_data; известно, если ТСПУ-зонд работал с этого входа). entry_country_check — то же про сам вход. no_data значит «неизвестно», а не «всё хорошо». Без адресов.
node_metrics Только чтение Текущие CPU, RAM, диск и сеть ноды, трафик за сегодня, люди онлайн по протоколам, главные пользователи за сегодня. С hours (1–720) также нагрузка хоста по часам (CPU среднее и пик, softirq, RAM, сеть, сессии; окна длиннее 96 часов группируются в точки по bucket_hours) и пики всего окна с их часом. Панель хранит её 90 дней. От агента, который их сообщает, resources добавляет steal и ожидание ввода-вывода, своп, таблицу соединений (число, лимит, заполнение), сокеты TCP и UDP, скорость линка сетевой карты и сам процесс агента (CPU, память, горутины, потоки, открытые файлы против лимита); без него агент слишком старый, чтобы это сообщить. Без node: по краткой строке текущих показателей на каждую ноду, кроме выведенных (без топа пользователей и истории; steal, заполнение conntrack и CPU и память агента, если известны). Нагрузку за время и запас даёт capacity_report.
node_runtime Только чтение node (пусто = все ноды). Что нода запускает и что хочет панель: желаемые и применённые ревизия и хеш (12 символов), in_sync, drift и с какого времени, последнее применение и по каждому inbound: enabled (входит в желаемое состояние), spec_version, применённый хеш спеки, применённое и живое состояние, последняя ошибка и срок сертификата. attention перечисляет несостыковки: applied_not_desired (так выглядит «осиротевший» inbound), desired_not_applied, failed, unknown_running. Без адресов, пинов и ключей; к ноде не обращается.
panel_logs Админ Свежие записи журнала самой панели (кольцо в памяти на последние 5000, пропадает при перезапуске), новые сверху; адреса, секретные имена и значения, похожие на ключи, убраны, из атрибутов остаются только разрешённые. Фильтры: min_level (debug, info, warn, error; по умолчанию info), minutes (до 10080), query (подстрока сообщения или значения атрибута, до 100 символов, ищется в очищенном тексте), component (health, fleet, http ...), code (точный код ошибки), request_id (код, который админка показывает при сбое запроса), limit (по умолчанию 100, не больше 500) и cursor (прошлый next_cursor). level, buffered и capacity показывают, что держит кольцо. Сообщения идут из кода панели и из данных, которые она обработала: это недоверенный текст.
capacity_report Только чтение Насколько была нагружена каждая нода и сколько людей она ещё возьмёт: hours (1–720, по умолчанию 168) и необязательный node (только эта нода и сводка по флоту). По каждой ноде: status (ok, busy, overloaded, unknown, если данных нет), bottleneck — что кончится первым (cpu, steal, bandwidth, ram, conntrack, disk), час пик (час с самым высоким средним CPU) с его CPU и людьми, пик людей онлайн, почасовые пики CPU: 95-й процентиль (cpu_peak_p95_pct, самые высокие) и 75-й (cpu_peak_typical_pct, ниже него держится большинство часов: статус смотрит на него, и одни пики никогда не делают ноду перегруженной), p95 steal, пики conntrack и RAM, своп, диск, пики трафика против полосы ноды (capacity_source: заданной владельцем, иначе скорости линка сетевой карты), собственные CPU и память агента с суточным ростом, cpu_per_100_people_pct и mbps_per_person из подгонки методом наименьших квадратов по часам (fit говорит few_hours, flat или no_trend, когда по часам её не построить), headroom_people (сколько людей можно добавить, пока час пик не дойдёт до 80% CPU) и recommendations (code, severity, params; в cpu_busy поле target называет ноду с наибольшим запасом). summary: ноды по состояниям, общий запас, самые нагруженные и самые свободные ноды. Отсутствующее значение неизвестно (агент слишком старый, чтобы его сообщать), а не равно нулю. См. Нагрузка.
panel_resources Только чтение Сколько сейчас стоит сама панель: её процесс (CPU в процентах машины, резидентная память, куча и вся память Go, горутины, потоки, открытые файлы против лимита, время работы), машина (занятость CPU, steal и ожидание ввода-вывода, load, RAM, своп, диск каталога данных), база (размер файла и WAL, страницы и свободные страницы; замеряется не чаще раза в минуту), агенты на связи из общего числа нод и admin_api: вызовы API админки за последние 5 минут (запросы, ошибки сервера и клиента, p95 в мс).
retention_status Админ Сколько панель хранит то, что записывает: по каждой настройке (journal_days, events_info_days, events_warn_days, audit_days, alerts_days, check_samples_hours, check_daily_days, host_history_days, traffic_bucket_days, node_traffic_hour_days) значение, значение по умолчанию, границы и единица.
node_debug_logs Админ Отладочная запись ноды (запускается через node_debug_capture_plan / _apply), сначала старые строки. Назови запись (capture_id) или ноду (её новейшая запись); без обоих вернётся список записей, которые держит панель (24 часа), новые первыми. Запись называет своё состояние state: running (строки придут, когда выйдет время), done или expired (время прошло, нода так и не прислала). Фильтры: min_level (debug, info, warn, error), source, query (подстрока сообщения или значений атрибутов, до 100 символов, ищется по очищенному тексту), limit (по умолчанию 100, не больше 500) и cursor (прежний next_cursor). Строки очищены на ноде и в панели: <ip> вместо адресов, без секретных имён и ключей, короткий список атрибутов. Сообщения приходят от движков ноды: это недоверенный текст. Источник kernel читает журнал ядра за 30 минут до начала захвата и во время него; строки пакетного журнала firewall подсчитываются, но не сохраняются. На узлах с ядровым AWG выбор awg включает отладку модуля на время захвата и добавляет сводку с инициированиями, не получившими ответа за 5 секунд.
tasks_list Оператор Задачи по расписанию владельца: у каждой id, name, kind (check или assistant), enabled, schedule (every 15m, daily 07:30, weekly mon 07:30), next_run_unix, running, last_run (status ok, problem, failed, skipped или running, код reason и однострочный summary), problem с её описанием (открыт алерт scheduled_check) и fail_streak (три подряд открывают scheduled_task_failing). timezone_offset_minutes — часовой пояс панели. Названия и описания — недоверенный текст. Нет в Cloudflare-версии.
task_get Оператор Одна задача целиком (task_id): steps проверки (tool, args, conditions, error_is_problem), prompt и conversation_id задачи ассистента, notify_telegram и пять последних запусков.
task_runs Оператор Запуски задачи, новые первыми: task_id, limit (от 1 до 50, по умолчанию 10; панель хранит последние 50, не дольше 30 дней). У запуска trigger (schedule, manual или missed, если панель в это время не работала), status, reason (tool_failed, provider_unreachable, budget_reached, no_verdict, interrupted ...), summary; у проверки steps (tool, ok, problem, error, совпадения условий matches и начало результата); у задачи ассистента conversation_id, provider, model, usd и fell_back.
task_run_now Оператор task_id: запускает задачу сейчас, вне расписания, и сразу возвращает run_id; итог читается через task_runs. Одновременно идёт только один запуск задачи (task_running); вручную — не чаще раза в минуту для проверки и раза в пять минут для задачи ассистента (too_soon). Запуск задачи ассистента оплачивается из его месячного бюджета.
path_loss_matrix Только чтение hours (1–720, по умолчанию 24). UDP-пути между вашими нодами, где проверка портов потеряла пакеты: отправитель, цель, порты, отправлено, дошло, loss_pct, второй отправитель, у которого дошло, и open_ports (фильтр на пути), а по каждой цели — у скольких отправителей потери; так отличают плохую ноду от плохого пути. Только имена нод.
access_report Только чтение Что не открывается у людей, у кого и что чинить, одним вызовом. hours (1–168, по умолчанию 24) и необязательные country, group (id или точное имя), node, protocol. matrix: по ноде и серверу (протокол, транспорт, порт, CDN) устройства и люди, которые пробовали и у которых получилось, success_pct (для VLESS его нет: счётчика попыток нет), отказы в той мере, в какой их различают счётчики, зависания, заморозки и потери, а также люди, которым сервер выдан, но которые ни разу не подключались; то же по группам. country: вердикт по стране, порты TSPU, тёмные и доступные операторы и отчёты kl!ck по операторам и типам серверов. block_diagnosis и findings: машинные коды с ссылками на доказательства и числом затронутых людей и групп. recommendations: по рангу, у каждой вид, цель, почему, ожидаемый эффект и plan_tool (relay_plan, profile_update_plan, group_update_plan, profile_create_plan, node_ipv6_plan, node_update_plan) или next_tool. С агентами links/3 reject_split говорит и почему: no_reply, cert_refused, alerts_sent, alerts_recv, reality_fallback, reality_auth_failed, answers_lost и unanswered; у ячеек VLESS есть tcp_stalls и tcp_stalls_16k, а среди signals — tcp_freeze_16k, answers_lost и cert_refused. Правила фиксированы, недостающий сигнал помечается как неизвестный. Сервер, который выдан только через реле (прямая строка выключена в подписках), считается выданным и рабочим путём, пока его для человека несёт здоровое реле: включено, активно, последняя проверка пройдена, свежий круг монитора и не два провала подряд, а его вход разрешён этому человеку; заблокированная нода, у которой каждый выдаваемый сервер идёт через такие реле, даёт находку info с detail.why reached_through_relays. add_relay называет только серверы, которые реле может нести (AmneziaWG реле нести может, сервер за CDN нет), и не предлагает вход из страны самого выхода. Только счётчики и имена.
block_diagnosis Только чтение Как именно заблокирована нода, а не только заблокирована ли: необязательные node, country, hours. По ноде, порту или протоколу: класс с уверенностью, ссылками на доказательства, операторами и регионами, что неизвестно, и следующие шаги с plan-инструментом: ip_blocked, port_blocked, tcp_throttled, udp_blocked, protocol_fingerprinted, whitelist_mode, operator_specific, regional, not_blocked_but_broken, unknown. С агентами links/3 причины решают больше: tcp_throttled — и по собственным соединениям VLESS ноды, вставшим после 8–32 КиБ; protocol_fingerprinted и udp_blocked сильнее, когда нода ответила, а ответы потерялись (Hysteria2 hs_unfinished, AmneziaWG responses_unmatched), а рукопожатия REALITY, на которые нода ответила и которые так и не завершились, — это обрыв после ClientHello; not_blocked_but_broken (с detail.reason) охватывает и приложения, не принявшие сертификат ноды, и инициации AmneziaWG без ответа ноды, и проверку REALITY, которую не проходит никто. Без этих счётчиков (старый агент, бэкенд AWG в ядре) класс говорит, что неизвестно. Только сохранённые данные, ноды не опрашиваются.
node_doctor Только чтение Последний сохранённый отчёт доктора одной ноды или всех, с идентификаторами исправлений. Начиная с профиля «Оператор» принимает ещё refresh: true: нода прогоняет проверки сейчас (только читает хост; ждёт до 30 секунд). С refresh: true и без node свои проверки запускает каждый подключённый узел (не больше 24 узлов за раз); kept_last_report называет узлы, у которых остался прошлый отчёт: они не в сети или их агент слишком старый.
node_ports Только чтение Сохранённые проверки доставки UDP, доступности TCP и входящее подключение/профиль на каждом порту: direct_in_subscriptions показывает, указан ли адрес ноды, а cdn — подключаются ли клиенты через CDN-хост. Профиль «Оператор» может передать check: true для ограниченной проверки (около 15 с). Без node: по краткой строке на каждый узел, кроме выведенных, только сохранённые результаты (для check нужен узел).
checks_run_now Оператор Запускает проверки здоровья сейчас, не дожидаясь следующего раунда, и возвращает свежие результаты в форме checks_results для проверенных inbound. node: один узел, пусто = все узлы; inbound: только этот inbound. Панель делает не больше одного раунда на inbound раз в 30 секунд: слишком ранний запрос отклоняется сообщением, которое отсылает к checks_results. Ждёт до 25 секунд; complete: false значит, что часть раундов не закончилась.
path_probe Оператор Сразу отправляет тестовый трафик между двумя вашими нодами: from, to (id нод или точные имена), kind — udp, tcp или tls, необязательные ports (часть собственных портов цели; порт, которого цель не обслуживает, отклоняется). udp: 150 помеченных датаграмм на порт, отправлено и дошло, вердикт (ok, lossy, broken). tcp: обычное соединение с каждым TCP-портом цели, с временем в миллисекундах. tls: рукопожатие с собственным именем цели и пином сертификата (ours только для настоящего слушателя), со временем. mtu_sweep: true (или sizes, до 5 размеров данных от 64 до 1472) шлёт по десять датаграмм каждого размера с флагом «не фрагментировать» на один порт и возвращает largest_size — наибольший размер, из которого дошла хотя бы половина. Цели — всегда ноды флота: назвать хост или URL нельзя. Нужен агент с поддержкой проб у отправителя (иначе agent_too_old), а для udp ещё и нода-цель онлайн. Ограничено по частоте: одна проба на пару нод, не больше 6 на ноду за 5 минут и 12 на токен за 10 минут. Результаты хранятся 7 дней. Не только чтение: инструмент отправляет трафик. Только имена нод, никогда адреса. Нет в облачной редакции Cloudflare.
node_trace Оператор Обход TCP SYN с растущим TTL от вашей ноды (from) до другой (to): по каждому хопу время ответа и ответил ли маршрутизатор; хоп цели носит имя ноды, остальные — hop N (адреса сторонних маршрутизаторов не возвращаются). Сравнивает с предыдущей трассировкой пары (хранятся последние 20): diff и changed_at_hop говорят, что маршрут стал длиннее или короче или хоп перестал отвечать. Маршрут, изменившийся при той же длине и тех же ответах, выглядит как прежний. Те же ограничения, что у path_probe; только Linux-ноды.
node_dns_check Оператор Собственный резолвер ноды: время ответа (p50_ms, p95_ms) и сбои по контрольным доменам доктора, свежий запуск, последние 24 запуска и trend (steady, slower, faster, unknown до четырёх запусков). Если не задано stored_only: true, сейчас запускает проверку резолвера доктора; сохранённые результаты доктора попадают в историю. Те же ограничения, что у path_probe.
users_search Только чтение Пользователи по части имени, filter (online, expiring, over_quota) или group_id; по страницам через page_token.
groups_list Только чтение Группы с идентификаторами профилей, числом пользователей и DNS-пресетом.
group_get Только чтение Одна группа: идентификаторы профилей, исключённые ноды, DNS-пресет, цвет, пользователи и текущие серверные итоги, которые она открывает. В API групп нет полей заметки и квоты.
dns_presets_list Только чтение DNS-пресеты, правила резолверов и раздельного разрешения, фактическое число пользователей, статус «по умолчанию», каталог провайдеров и поддержка транспортов клиентами.
dns_preset_get Только чтение Один DNS-пресет по идентификатору с правилами резолверов и раздельного разрешения, числом пользователей и статусом «по умолчанию».
protocols_list Только чтение Протокольные плагины, клиентские приложения, компактная схема настроек (включая критичные и секретные поля) и настройки по умолчанию. Секреты в значениях по умолчанию скрыты. experimental стоит у протокола, который новый и ещё не проверен на практике (MTProto).
profiles_list Только чтение Сводка профилей: протокол, число нод и пользователей, предупреждения, форматы подписок, версия и группы, дающие доступ.
profile_get Только чтение Сводка одного профиля и настройки с замаскированными секретами; входящие подключения с ID и именами нод, действующим и переопределённым портом и именем сервера, состоянием и включённостью, direct_in_subscriptions (попадает ли адрес ноды в подписку) и cdn (подключаются ли клиенты через CDN-хост); группы, дающие доступ. Принимает profile_id.
user_get Только чтение Один пользователь: лимиты (оба лимита скорости), статус, четыре переключателя приложений (app_happ, app_amnezia, app_telegram, app_mistgate), устройства, профили (у каждого — форматы подписки, которые его несут), доступ к нодам. Без ссылки подписки и без ключей.
user_traffic Только чтение Израсходовано и квота, последние 14 дней, разбивка по нодам и протоколам.
user_devices Только чтение Устройства: вид, платформа, модель, версия ОС, приложение, трафик, когда были онлайн, онлайн ли сейчас и на каких нодах, короткий отпечаток ID устройства, для AmneziaWG — профиль и адрес в туннеле; заблокированные устройства отдельно. Никогда ключ или конфигурация.
subscription_preview Только чтение Какой формат получит клиент (идентификатор клиента или User-Agent) и какие профили (у каждого — форматы подписки, которые его несут) и ноды даёт доступ пользователя. Не сама подписка и без ссылки.
subscription_settings_get Только чтение Страница подписки, которую видит каждый пользователь: приложения, настройки страницы, упорядоченные правила выдачи по User-Agent, DNS по умолчанию для инстанса, предложение DNS в приложениях по ссылке, режим лимита устройств по ссылке, переключатели AmneziaWG в ссылке и автоматического выбора сервера, настройки пинга Happ, шаблон имён серверов, название, объявление, ссылка поддержки и интервал обновления. Также текущее число пользователей общей ссылки и ключей AmneziaWG по ссылке. Без чьей-либо ссылки или ключа.
alerts_list Только чтение Активные алерты; с include_history ещё и закрытые (window_s до 30 дней). min_severity (info, warning, critical) и kind сужают список.
health_summary Только чтение Краткая сводка: число развёрнутых синтетических проверок по последнему статусу и активных алертов по важности. Отдельные строки смотрите через alerts_list или checks_results.
reachability_history Только чтение Страна, семейство адресов, активные источники страницы «Доступность» и построчная по источникам хронология вердиктов каждой ноды за 1–7 дней. family: 4 (IPv4) или 6 (IPv6).
events_search Только чтение Лента событий по ноде, пользователю, min_severity (info, warning, error) или точному code, а hours оставляет последние N часов (от 1 до 168); по страницам через before_id. family (profiles или agent) выбирает события о профиле на узле (движок, профиль, хоп, учётные данные) или все остальные.
checks_results Только чтение Проверки глазами клиента: ноды по профилям, последний результат, неудачи подряд и 24 часа истории. Время ответа (через открытый туннель), время подключения и медианы за час, измеренные на сервере панели; у Hysteria2 ещё udp_sent и udp_lost (сколько пакетов собственный клиент QUIC панели отправил и потерял в последнем круге, дорога к ноде), udp_sent_hour, udp_lost_hour и node_sent_hour, node_lost_hour (дорога обратно, счёт самой ноды); udp_loss, когда сервер панели теряет UDP по дороге к некоторым нодам (их UDP-круги на 600 мс и больше медленнее VLESS до той же ноды), с lost_permille (туда) и node_lost_permille (обратно). Когда включена проверка из страны (см. Доступность), у каждой строки есть country_check: последний вердикт проб внутри страны с названиями сетей и его confidence (eyeball: домашние и мобильные сети, dc_only: только датацентры, listed: только список блокировок). Вердикт может быть partial: часть домашних или мобильных сетей не получает от ноды ничего, хотя до других ваших нод достаёт, а из других сетей нода видна. Когда включён Globalping, probes перечисляет спрошенные сети, у каждой eyeball (домашняя или мобильная проба) и, в раунде partial, dark (она ничего не получила от этой ноды, но достала до другой); no_probe называет операторов, у которых в этом раунде не было домашней или мобильной пробы онлайн. Когда включены списки блокировок, в нём есть ещё listed_by (antifilter_ipsum, antifilter_community), cdn_provider и cdn_region, а вердикт может быть listed: адрес в реестре, живьём его никто не проверял, и алерт он никогда не открывает. Когда включён ТСПУ-зонд, в country_check есть ещё sources (globalping, tspu, lists) и два вердикта, из которых он сложился (globalping_verdict, tspu_verdict); tspu это взгляд ноды-зонда на ноду (probe_node, at_unix, dpi_hop и ports, каждый blocked, open, refused или timeout), всегда из дата-центра (dc_only). Когда включены cheburcheck или bsbord, sources называет ещё cheburcheck, cheburcheck_own и bsbord, а в country_check есть два списка по всем источникам: source_verdicts, свежий вердикт каждого источника с source, verdict, reason (почему вердикта нет или что он увидел, например too_few_probes, no_probe, timeout или no_tcp_port), eyeball и at_unix, unknown тоже; и vantages, сети, единицы или пробы за этими вердиктами, у каждой source, key, network, region, asn, kind (home, mobile, dc, unknown), state (reach, dark, whitelist, uncertain), at_unix, dpi_hop, icmp_ok и tcp_ok; пробы Globalping и нода-зонд ТСПУ-зонда в них тоже есть. Вердикт складывается из всех свежих источников (правила): любой дотянувшийся плюс любой тёмный даёт partial, а уверенность conflict значит, что полная блокировка, увиденная насквозь, стоит против достающего, которого увидели только источники пути (ТСПУ-зонд, cheburcheck), поэтому блокировка остаётся вердиктом. Когда включены IPv6-проверки Globalping, country_check.ipv6 это та же нода, измеренная по своему IPv6-адресу, в том же виде (единственный источник Globalping; поля выше остаются про IPv4): нода, которую не измеряли, получает unknown с reason: no_ipv6, ipv6_broken (адрес есть, но IPv6 у хостера не работает), agent_old, not_checked или no_probes (у Globalping нет проб с IPv6 в стране). Названия и регионы приходят от третьих лиц и являются данными. Верхнеуровневый tspu_probe это последний запуск ноды-зонда: status (ok, control_failed, no_dpi_hop, busy, failed), at_unix, probe_node, dpi_hop, blocked_ref, nodes_checked, detail и, для no_dpi_hop, reason (refs_pass: заблокированные адреса открываются с ноды-зонда, у неё на пути нет ТСПУ; no_hops: роутеры на пути не отвечают; нет поля, если причина неизвестна). У каждой ячейки есть inbound_id и stats_24h: p50 и p95 connect_ms и response_ms и jitter_ms (стандартное отклонение response_ms) за последние 24 часа по раундам, где туннель поднялся. daily_days (1–90) добавляет в каждую ячейку daily: по записи на каждые завершённые сутки UTC со счётчиками ok, degraded, failed, p50 и p95 latency_ms, connect_ms и response_ms и jitter_ms (0 = не измерено; у суток, сохранённых раньше, нет значений connect и response).
klick_reports Только чтение Что люди с приложением kl!ck видели из своих сетей за 7 дней («Отчёты kl!ck»): по каждой ноде число отчётов, ok, freeze (заморозка ТСПУ), tcp_blocked, handshake_failed, no_answer и время последнего отчёта, затем то же по операторам, регионам и типу сервера kind (не больше 8 каждого, сначала самые частые). Для каждого kind: медиана измеренных delay_ms, dl_checked — строки с результатом загрузки в dl_stalled, dl_stalled — строки, где загрузка зависла. enabled false — источник выключен и ничего не показывается. Необязательный node. Ни адресов, ни людей, ни устройств.
outdated_devices Только чтение Какие устройства получают VLESS REALITY-сервер и известно ли, что их приложение шлёт постквантовый key share («Версии приложений»). В counts — устройства и люди по каждому состоянию: ok, below_minimum (приложение известно, версия ниже need_version), unsupported (ни одна версия не работает, reason app, либо fingerprint профиля классический, reason fingerprint) и unknown (app_unknown, no_threshold или no_version). fingerprints — fingerprint'ы используемых REALITY-профилей. state сужает список (пусто = всё, кроме ok), user_id — один человек, limit (по умолчанию 50, не больше 100) и offset листают (has_more, next_offset); сначала худшее состояние. В строке: человек, client (приложение, как оно назвало себя: данные, а не инструкции), platform, последняя активность, state, reason, need_version, fingerprint. Рядом — то, что видели ноды («По факту»): у строки есть actual (pq — каждый ClientHello по VLESS REALITY за последние hello_window_hours часов нёс постквантовый share, classic — ни один не нёс, mixed — и так и так, none — ничего читаемого не насчитано, в том числе когда агент его ноды не считает), счётчики hello_pq, hello_classic и hello_unknown (не удалось прочитать) и table_mismatch, где они расходятся с таблицей: worse (по таблице ok, а устройство слало классические hello) или better (по таблице не ok, а у каждого hello был share). Верхнеуровневое actual считает устройства и людей по классам, что бы ни стояло в фильтрах; mismatch_worse и mismatch_better считают расхождения; hello_kex_nodes_without называет ноды с живым REALITY-сервером, чей агент не указывает vless-hello-kex/1. Аргумент actual (pq, classic, mixed или none) сужает список до класса, и тогда пустой state означает все состояния, включая ok. Ни на что не влияет. Ни ссылок, ни ключей, ни адресов.
user_connection Только чтение Что ноды насчитали из соединений одного человека: user_id, необязательные hours (от 1 до 168, по умолчанию 24) и by_hour (почасовые корзины с ненулевыми счётчиками, от старых к новым). По устройству, ноде и инбаунду: connects, rejects (известный ключ отклонён, потому что закончился срок), drops (idle-закрытие Hysteria2 в первые 60 секунд или до 64 КиБ; само по себе не отличает замороженный путь от короткой проверки приложения), stalls (10-секундные раунды AmneziaWG: инициирующие пакеты дошли до ноды, рукопожатие не завершилось), online_s (включает idle-хвост коротких сессий), last_hour_unix, platform, client и kind устройства. Строка ключа AmneziaWG через ретрансляцию — отдельная строка с via_country и via_node_id (вход); на прямом пути их нет. На Hysteria2 с links/2: client_closes — клиент закрыл соединение сам; freezes — нода продолжала отправлять, но до idle timeout не получила ответ (признак заморозки пути, в отличие от проверки приложения; клиент также мог исчезнуть во время передачи); quiet — клиент ушёл, пока обе стороны молчали (обычно безвредная проверка приложения или спящий телефон); accepted — завершённые QUIC-рукопожатия; hellos_foreign — ClientHello с чужим именем сервера; эти inbound-счётчики нельзя распределить по устройствам. rtt_ms — среднее сглаженное RTT по rtt_samples; loss_permille — потерянные по мнению ноды пакеты на тысячу отправленных (pkts_sent). hours содержит те же счётчики, ненулевые поля опущены. Поля links/2 равны нулю для AWG, VLESS и Hysteria2 без links/2, поэтому такие нули ничего не значат. С агентами links/3 у строки есть и причины по ключу: tcp_stalls и tcp_stalls_16k (VLESS поверх REALITY TCP: соединения, данные которых клиент перестал подтверждать, и из них вставшие после 8–32 КиБ — заморозка ТСПУ) и initiations, responses, responses_unmatched (AmneziaWG на userspace-бэкенде: инициации, дошедшие до ноды, её ответы и ответы, которые устройство так и не подтвердило); unsupported называет те из пяти, которых у строки быть не может (протокол, транспорт, бэкенд AWG или старый агент). У строк VLESS REALITY агентов с vless-hello-kex/1 есть ещё hello_pq, hello_classic и hello_unknown: ClientHello устройства по обмену ключами (объяснение в fleet_connections). nodes_without_counters — доступные ноды без счётчиков links/1. Только числа: без адресов и времени отдельного соединения.
node_connections Только чтение Что нода насчитала из попыток: node (ID или точное имя), необязательные hours (от 1 до 168, по умолчанию 24) и by_hour (почасовые корзины с ненулевыми счётчиками, от старых к новым). У VLESS unknown_keys доступен с vless-unknown-keys/1; старые агенты считают его неподдерживаемым. По инбаунду, вместе по всем ключам: connects, rejects, drops, stalls, online_s, unknown_keys, hellos, handshakes, keys_stalled, keys_tried, unsupported, clients (приложение и платформа, максимум 8, сначала самые активные), hours, а для AWG — awg (последний отчёт: UDP-пакеты, время, backend и онлайн-пиры). Для Hysteria2 с links/2: client_closes — клиент закрыл соединение сам; freezes — нода продолжала отправлять, но до idle timeout не получила ответ (признак заморозки пути, в отличие от проверки приложения; клиент также мог исчезнуть во время передачи); quiet — клиент ушёл, пока обе стороны молчали (обычно безвредная проверка приложения или спящий телефон); accepted — завершённые QUIC-рукопожатия; hellos_foreign — ClientHello с чужим именем сервера. rtt_ms — среднее сглаженное RTT по rtt_samples; loss_permille — потерянные по мнению ноды пакеты на тысячу отправленных (pkts_sent). unsupported перечисляет счётчики, которые этот протокол или агент не сообщает; их нули ничего не значат. supported false — агент не присылает links/1, поэтому inbounds пуст. В строках clients есть rtt_ms и loss_permille, но фиксированный формат не передаёт знаменатели rtt_samples и pkts_sent по приложениям. С агентами links/3 — почему рукопожатия не удаются, там, где движок это видит: hs_unfinished (нода ответила на ClientHello, а рукопожатие так и не завершилось), tls_alerts_sent, tls_alerts_recv, tls_cert_refused (приложения не приняли сертификат ноды: наша сторона), reality_fallback и auth_failed (VLESS REALITY: отдано сайту как не клиент; наше имя с чужим ключом или short id), tcp_stalls и tcp_stalls_16k (VLESS), initiations, responses, responses_unmatched (AmneziaWG, только userspace-бэкенд: бэкенд в ядре их не различает); VLESS считает ещё hellos, hellos_foreign и поверх REALITY TCP — connects. unsupported называет и то, чего не видят транспорт VLESS или бэкенд AWG. Без адресов.
fleet_connections Только чтение Те же суммы по инбаундам, что в node_connections, для всех нод, кроме выведенных из флота, по имени: необязательный hours (от 1 до 168, по умолчанию 24), supported и inbounds. Если есть отчёт здоровья, AWG-инбаунд включает awg. В сводке нет clients и почасовых корзин. Drops — idle-закрытия Hysteria2 в первые 60 секунд или до 64 КиБ; сами по себе они не отличают замороженный путь от короткой проверки приложения. Для Hysteria2 с links/2: client_closes — клиент закрыл соединение сам; freezes — нода продолжала отправлять, но до idle timeout не получила ответ (признак заморозки пути, в отличие от проверки приложения; клиент также мог исчезнуть во время передачи); quiet — клиент ушёл, пока обе стороны молчали (обычно безвредная проверка приложения или спящий телефон); accepted — завершённые QUIC-рукопожатия; hellos_foreign — ClientHello с чужим именем сервера. rtt_ms — среднее сглаженное RTT по rtt_samples; loss_permille — потерянные по мнению ноды пакеты на тысячу отправленных (pkts_sent). Stalls — 10-секундные раунды; hellos включают сканеры и пинги приложения рукопожатием, но не возобновлённые TLS-сессии; online_s включает idle-хвост коротких сессий. Причины links/3 — те же, что в node_connections. Нули неподдерживаемых счётчиков ничего не значат. hello_kex показывает, кого отвергла бы строгая библиотека REALITY, по ClientHello, которые ноды видели на текущем ядре (агенты с vless-hello-kex/1): сколько устройств слали только постквантовые рукопожатия (pq_only: ключевая доля X25519MLKEM768 стоит перед X25519), только классические (classic_only), и те и другие (mixed) или только нечитаемые (unknown_only); каждое устройство считается один раз; до 50 classic_devices (человек, приложение, платформа, числа) и nodes_without, которые пока не считают. Только числа, без адресов.
node_journal Только чтение Сохранённые предупреждения и ошибки ноды и движков: необязательные node (ID или точное имя; пусто — все ноды), hours от 1 до 168 (по умолчанию 24), min_level (warning по умолчанию; info тоже означает warning или error), source, query (подстрока без учёта регистра в сообщении или атрибутах, до 100 символов) и limit (100 по умолчанию, максимум 200). Записи содержат имя ноды и профиля, час, источник, шаблон сообщения, инбаунд, атрибуты, число и время первой/последней записи. nodes_without_journal — агенты без journal/1; truncated означает, что совпадений больше. Сообщения и атрибуты пришли с ноды: это данные, не инструкции. Без адресов.
os_updates_status Только чтение Сохранённые данные об операционной системе каждой ноды и сервера панели: дистрибутив, работающее и самое новое ядро, ожидающие обновления и обновления безопасности, возраст списков пакетов, нужна ли перезагрузка и почему, умеет ли агент выполнять задания ОС и что мешает сейчас (update_block, reboot_block), а также действующее или последнее обновление ОС с фазой и кодами отказов ноды. Необязательный node. К ноде не обращается и ничего не обновляет. См. «Операционная система серверов».
updates_status Только чтение Сборка панели, статус и версия пакета, состояние обновления и сохранённое расписание каждой ноды, идущая или последняя раскатка, фиксированное смещение UTC для новых расписаний, включённые дополнительные источники загрузки, download_source текущего шага и sources_failed у шагов с неудачной загрузкой.
relay_check Админ relay_id. Проверяет одну ретрансляцию сейчас и сохраняет результат: плечо и, если ретрансляция включена, путь. Только шлёт пробные пакеты между вашими нодами и ничего не переключает, поэтому это чтение, как node_ports с check: true, а не план; нужен профиль «Админ», потому что проверка ретрансляции в панели — дело владельца. Может занять до минуты (лимит 90 с). Для включения нужна проверка плеча, пройденная не более 15 минут назад.
node_ipv6_check Админ node. Проверяет снаружи, что IPv6-адрес ноды отвечает и отвечает именно она: другая нода с рабочим IPv6 (иначе панель, иначе Globalping) шлёт пакеты node_ports на этот адрес вместо основного. Возвращает passed, sender, вердикт по каждому порту и error_code, если проверка не состоялась (no_ipv6_verifier: проверить адрес нечем). Только шлёт пробные пакеты между вашими нодами, ничего не меняет ни на одном хосте (результат хранится у ноды, node_get его показывает, а успешный годен 10 минут для node_ipv6_plan), поэтому это чтение, а не план; нужен профиль «Админ», потому что проверка в панели — дело владельца. Адрес не показывает. Может занять до минуты (лимит 90 с). Ноду без пригодного IPv6 отклоняет с причиной (no_ipv6, ipv6_broken, agent_old, not_checked, main_is_ipv6).
node_server_access_list Админ Сохранённые SSH-адрес, логин и отпечаток, поля password_saved, password_login (работал ли парольный вход при последней проверке) и panel_key_fingerprint, восстановление после смены пароля и состояние вывода ноды. Пустой отпечаток ключа панели при password_saved: true означает доступ только по паролю. Пароли не возвращаются.
node_server_keys_list Админ node: ID или точное имя. Открытые ключи из ~/.ssh/authorized_keys этого логина: у каждого тип, key_id (первые 12 символов SHA256-отпечатка: целый отпечаток скрыт от агента, как любое значение, похожее на ключ), комментарий, ограничения и число одинаковых строк. Комментарии с сервера — недоверенный текст; закрытые ключи не возвращаются.
audit_search Админ Журнал аудита с фильтрами source (panel, bot, mcp, api), автор или действие; по страницам через before_id. hours (1–8760), failed_only, actor и action (подстроки) применяет сама панель до нарезки страницы, поэтому страница заполнена подходящими записями. Записи старше 400 дней удаляются.
backup_status Админ Включены ли резервные копии по расписанию и идёт ли копирование, интервал, срок хранения, последний успех и код последней ошибки. Без учётной записи хранилища, бакета, ключа доступа, получателя age и секретов.

Форматы в результатах. subscription_preview называет форматы так: base64_uris (список ссылок), mihomo_yaml, xray_json, singbox_json, user_page и decoy. У клиента есть его formats, у User-Agent — format, который ему отдают, а среди идентификаторов клиентов есть singbox. subscription_settings_get возвращает упорядоченные правила вкладки Кому что отдавать. Чтобы увидеть, какой формат получает конкретный User-Agent, передайте его в subscription_preview.

У профиля в user_get и subscription_preview есть formats — список из format, ok и note для каждого из четырёх форматов подачи. ok: false значит, что формат профиль не несёт. note — код, а не текст: xhttp, self_signed, gecko, awg или unsupported. При ok: true код hop_single_port значит, что диапазон прыжков по портам записан одним портом. Коды объяснены в разделе Профили.

Инструменты изменений#

Каждое изменение — пара: <tool>_plan и <tool>_apply.

Инструмент Профиль Аргументы Нужен владелец
user_create Оператор name (от 1 до 64 символов, без повторов без учёта регистра), group_id, по желанию quota_bytes, quota_reset (none, day, week, month (по умолчанию), rolling_month), term_days (не больше 3650), device_limit (не больше 100), apps (happ, amnezia, telegram), nodes (all или node_ids), speed_limit_bps (на человека: все его устройства вместе на одной ноде), device_speed_limit_bps (на устройство), dns_preset_id нет
user_update Оператор user_id, при необходимости subscription_name (не длиннее 64 символов; пустое значение использует name), и только меняемые поля (как выше, с expires_unix вместо term_days; в плане названы оба лимита скорости: на человека на одной ноде и на устройство) нет
user_disable Оператор user_ids (от 1 до 50) если пользователей больше 3
user_enable Оператор user_ids (от 1 до 50) нет
user_reset_traffic Оператор user_ids (от 1 до 50) если пользователей больше 3
device_revoke Оператор user_id, device_id и, по желанию, block (этот ID устройства не зарегистрируется снова, пока владелец не разблокирует его в админке; приложение с другим ID — новое устройство; заблокировать можно только приложение, которое присылает ID устройства) нет
alert_mute Оператор alert_id, duration_s (не больше 604800; 0 снимает заглушку) нет
alert_close Оператор alert_id; закрывает алерт без уведомления, и он остаётся закрытым, пока длится та же проблема нет
subscription_app_upsert Оператор platform (ios, android, windows, macos, linux) и name указывают приложение; для изменения — только меняемые поля, для нового приложения — как минимум kind: kind (happ принимает ссылку подписки, amnezia — ключ AmneziaWG), download_url, add_link_template (подстановки {url}, {url_enc}, {name_enc}), description (не длиннее 80 символов), recommended всегда
subscription_app_remove Оператор platform, name всегда
subscription_rules_set Оператор Полный упорядоченный список rules из ua_contains и format (base64_uris, user_page, decoy, mihomo_yaml, xray_json, singbox_json); срабатывает первое совпадение всегда
subscription_texts_set Оператор Только изменяемые поля: title, announcement, support_url, update_interval_hours, server_name_template всегда
subscription_link_limits_set Оператор mode (track, enforce, strict), link_awg (включать AmneziaWG в приложения по ссылке), link_auto_select (ставить Auto первым в Mihomo, sing-box и Xray JSON) или любое сочетание полей. План строгого режима сообщает, скольким пользователям общей ссылки будет отказано; при выключении link_awg — сколько ключей ссылки пропадёт при следующем обновлении (ключи приложения Mistgate среди них не учитываются) всегда
subscription_page_set Оператор Только изменяемые поля: show_announcement, show_support, show_qr, device_self_service, page_password, dns_choice, happ_ping (off, tcp) и happ_ping_on_open всегда
dns_settings_set Оператор default_preset_id, упорядоченный link_preset_ids и link_default_preset_id; передавайте только изменяемые поля всегда
group_create Оператор name, необязательные profile_ids, dns_preset_id (пустое значение — по умолчанию для инстанса), color и disabled_node_ids. У групп нет заметок и квот нет
group_update Оператор group_id и только изменяемые поля: name, profile_ids, dns_preset_id, color, disabled_node_ids всегда
group_delete Оператор group_id пустой группы. Группа с людьми отклоняется; сначала переместите людей через user_update нет
dns_preset_create Админ name, description, servers, необязательные split, ipv4_only, split_direct, preferred_transport (plain, dot, doh), block_ads всегда
dns_preset_update Админ preset_id и редактируемые поля: name, description, servers, split, ipv4_only, split_direct, preferred_transport, block_ads всегда
dns_preset_delete Админ preset_id; встроенные пресеты и пресет по умолчанию для инстанса отклоняются, пользователи и группы переходят на значение по умолчанию для инстанса всегда
profile_create Админ План: protocol, name, необязательные JSON settings (отсутствующие поля берутся из настроек протокола по умолчанию), node_ids, существующие group_ids, port_overrides (порт по ID ноды), allow_lossy_port; применение: только confirm_token. Для поля x-secret пропустите значение, укажите "••••", чтобы сохранить его, или "$generate"; буквальный секрет передавать нельзя всегда
profile_update Админ План: profile_id, необязательные name, JSON Merge Patch RFC 7386 settings_patch (пропущенные секретные поля сохраняют прежнее значение; значения null внутри патча запрещены), allow_lossy_port; применение: только confirm_token. Для секретов действуют те же правила: пропустить, "••••" или "$generate" всегда
profile_deploy Админ План: profile_id, add_node_ids, remove_node_ids, существующие add_group_ids, remove_group_ids, необязательные port_overrides и allow_lossy_port; применение: только confirm_token всегда
node_fix Админ node, fix_id из отчёта доктора, params, если пункт их перечисляет всегда
node_decoy Админ node, mode (builtin, panel, own), bundle_base64 (ZIP- или TAR-архив в base64 до 2 МиБ, обязателен для own) всегда
node_update Админ node и только изменяемые поля: name, country_code, location, provider, notes и переключатели direct_in_subscriptions по входящим подключениям. Адрес и настройки времени выполнения не принимаются всегда
node_ipv6 Админ План: node, action (enable или disable); применение: только confirm_token. Включает или выключает вход по IPv6 ноды: дополнительный сервер «<нода> · IPv6» рядом с каждым сервером ноды в подписке у всех. enable сначала проверяет адрес снаружи (см. node_ipv6_check) и включает вход, только если проверка пройдена; ноду, которая не может принять вход, план отклоняет с причиной. План называет ноду и профили, серверы которых получат двойника, и никогда не показывает адрес; адрес — тот, который сервер использует для исходящего IPv6. всегда
node_awg_backend Оператор План: node, backend (auto, kernel или userspace); применение: только confirm_token. Задаёт, как нода запускает AmneziaWG. План показывает текущую настройку, что работает сейчас, не работает ли нода на запасном userspace, сколько устройств онлайн, замечание о переподключении (интерфейсы пересобираются, устройства переподключаются примерно за 20 секунд) и, при переходе на userspace, оценку памяти (26 КиБ на устройство). Модуль ядра не собирает. Ноду со слишком старым агентом, который не умеет следовать настройке, отклоняет применение. всегда
path_speed Админ План: from, to (id нод или точные имена), необязательные mb (от 8 до 32, по умолчанию 16) и direction (down: from скачивает данные с to, по умолчанию; up: загружает); применение: только confirm_token. Ограниченная проверка пропускной способности между двумя вашими нодами: to открывает короткоживущий TCP-слушатель на одно соединение (одноразовый токен, закрывается максимум через 30 секунд) и отдаёт данные, from забирает их и измеряет. Результат применения: мегабиты в секунду на всей передаче, время соединения, время до первого байта (down) и длительность; хранится 7 дней. Тест гонит трафик через каналы обеих нод, поэтому всегда ждёт владельца, как и собственный тест пропускной способности панели, доступный только владельцу. Пределы: не больше 32 МБ и 30 секунд, один тест на ноду одновременно, 6 на ноду и 12 на токен в сутки. Цели только ноды флота, не публичный сервер; обоим агентам нужен speed/1 (иначе agent_too_old), а тестовый порт цели должен быть доступен отправителю. В плане и результате имена нод, никогда адреса. Нет в Cloudflare-версии. всегда
warp_restart Админ node — идентификатор или точное имя; план перечислит профили с выходом через WARP, которые могут прерваться на несколько секунд; для применения нужен только confirm_token нет
warp_reregister Админ node — идентификатор или точное имя, необязательный reason (не длиннее 300 символов); для применения нужен только confirm_token. В плане есть ссылка на условия Cloudflare; одобрение владельца принимает их для этого аккаунта и заменяет его новым анонимным устройством, меняя IP-адрес выхода через WARP всегда
relay Админ План: action и его аргументы; применение: только confirm_token. create: node (вход, идентификатор или точное имя), inbound_id (из relay_candidates) и необязательно port (443 или от 1024 до 65535; не указан — порт выхода, если свободен на входе, иначе свободный). enable, disable и delete: relay_id. port: relay_id и port. План описывает изменение без адресов: вход, выход, сервер, порт, как страновая проверка видит оба конца, последняя проверка и что увидят люди; факт warning, если вход и выход в одной стране (подсказка, не отказ); для сервера AmneziaWG ещё факт awg_path_keys (каждый, кому разрешены обе ноды, получает свой ключ через вход; ключи AmneziaVPN нужно импортировать заново, приложения по ссылке получают его при следующем обновлении) и порт, который при свободном месте подходит под вид профиля всегда
rollout_start Админ План: nodes (от 1 до 20 id из updates_status; старый параметр node_ids тоже принимается, но не вместе с nodes); применение: только confirm_token. План показывает подписанную версию, порядок канарейки (сначала меньше людей онлайн, затем меньше входящих профилей), размер пакета, имя ноды, версию агента и число людей онлайн для каждой ноды; точный набор нод и версия/сборка пакета закрепляются в плане всегда (step-up)
os_rollout_start Админ План: node_ids (от 1 до 20 id из os_updates_status), mode (security, all: установить обычные и безопасностные пакеты, или reboot_only), необязательный batch_size (1–5, по умолчанию 1) и reboot (never или if_required для режимов пакетов; if_required или always для reboot_only); применение: только confirm_token. План закрепляет id, режим, перезагрузку и размер пакета. В нём показаны канарейка и порядок (сначала меньше людей онлайн, затем меньше inbound), а также недоверенное имя каждой ноды, ожидающие и безопасностные пакеты, следующее ядро, необходимость перезагрузки, онлайн-пользователи и блокировки перезагрузки; отдельно перечислены ноды, которые сейчас будут пропущены. Есть предупреждения об автоматической перезагрузке unattended-upgrades и отсутствии модуля AmneziaWG. всегда (step-up)
os_rollout_cancel Админ rollout_id из os_updates_status. Закрывает остановившееся обновление ОС (тревога снимается) или то, что ещё не началось; задание, уже идущее на ноде, остановить нельзя, это отклоняется всегда (step-up)
os_rollout_pause Админ План: rollout_id из os_updates_status; применение: только confirm_token. Ставит раскатку на паузу после того, как уже запущенные на нодах задания завершатся и пройдут проверку; остальные задания ждут всегда (step-up)
os_rollout_resume Админ План: rollout_id, необязательный skip_failed; применение: только confirm_token. По умолчанию один раз повторяет неудачные шаги; с skip_failed пропускает их и продолжает всегда (step-up)
node_update_schedule Админ План: node_id, local_datetime (YYYY-MM-DDTHH:mm в смещении из updates_status, не раньше чем через минуту и не позже чем через год); доверенная версия и смещение закрепляются в плане всегда
node_update_schedule_cancel Админ node_id всегда
update_timezone Админ timezone_offset_minutes (фиксированное смещение UTC к востоку, от -720 до 840 с шагом 15 минут; 180 — GMT+3) всегда
update_download_timeout Админ timeout_seconds (от 300 до 7200 секунд; действует для новых отправленных обновлений, а уже начатый шаг сохраняет своё окно) всегда
log_level Админ level (debug, info, warn или error). Задаёт уровень журнала панели до её следующего перезапуска, после чего он возвращается к --log-level / MISTGATE_LOG_LEVEL. Ничего не удаляет. нет
node_debug_capture Админ node, level (debug или info, по умолчанию debug), sources (до 8 источников журнала, например agent, hysteria2, xray, awg, kernel; пусто = все), duration_s (1–900, по умолчанию 300). Нода должна быть на связи, а её агент — объявлять debug/1; одна запись на ноду за раз. Нода поднимает уровень журнала для источников, копит до 20000 записей (4 МиБ) и присылает их очищенными, когда время выходит; уровень она возвращает сама. Результат читается через node_debug_logs. Пишется в аудит: кто просил, нода, источники и длительность. Источник kernel читает журнал ядра за 30 минут до начала захвата и во время него; строки пакетного журнала firewall подсчитываются, но не сохраняются. На узлах с ядровым AWG выбор awg включает отладку модуля на время захвата и добавляет сводку с инициированиями, не получившими ответа за 5 секунд. Для источника kernel требуется debug/2; для остальных достаточно debug/1. нет
retention Админ values: имя настройки и новое значение (имена, единицы и границы даёт retention_status). Более короткий срок удаляет старые строки при ближайшей почасовой чистке, насовсем. всегда (step-up)
task_create Админ План: name, kind (check или assistant), schedule (every 15m, every 2h, daily 07:30, weekly mon 07:30, в часовом поясе панели; проверка — не чаще раза в 5 минут, задача ассистента — раза в 15), для проверки steps (от 1 до 8: tool, args, conditions из path, op и value, error_is_problem), для задачи ассистента prompt (до 4000 символов), notify_telegram, disabled; apply: только confirm_token. План проверяет задачу по правилам самой панели: какие инструменты может вызывать проверка (чтение и замеры профиля оператора, без планов, apply и инструментов задач), аргументы по схеме каждого инструмента, условия, минимальный интервал и что ни в названии, ни в аргументах, ни в запросе нет секрета (secret_in_task). Не больше 50 задач. Задача принадлежит владельцу, её запуски работают с профилем оператора. всегда
task_update Админ План: task_id и только меняемые поля (name, schedule, steps заменяют все прежние, prompt, notify_telegram, enabled); вид задачи не меняется. Изменённая задача начинает с чистого состояния: её открытые алерты закрываются. Если задачу изменили в панели до apply, apply отвечает changed_since_plan. всегда
task_delete Админ План: task_id. Удаляются задача и её запуски, открытые алерты закрываются; разговор задачи ассистента остаётся у владельца. всегда
rollout_pause, rollout_resume, rollout_cancel Админ rollout_id из updates_status всегда
node_rollback Админ node всегда
node_install Админ План: host, port (по умолчанию 22), username (root или пользователь с sudo без пароля), имя ноды name (от 2 до 24 букв, цифр или дефисов), address, необязательно country_code, location, provider; применение: только confirm_token. План читает только открытый host key сервера. Host key подтверждает владелец, он же на экране одобрения выбирает ключ панели или вводит SSH-пароль; установка с паролем по умолчанию добавляет и ключ панели всегда
node_server_password_rotate Админ План: ID ноды или точное имя действующей ноды node (выведенная нода отклоняется); применение: только confirm_token. Новый пароль панель генерирует сама и никогда не возвращает; владелец может показать его на вкладке Сервер ноды всегда
node_server_key_add Админ План: node и одна открытая строка public_key либо panel_key: true; применение: только confirm_token. Владелец одобряет тип, отпечаток и недоверенный комментарий перед добавлением. Закрытый ключ не принимается. всегда
node_server_keys_add Админ План: nodes (от 1 до 20 id) и одна открытая строка public_key либо panel_key: true; применение: только confirm_token. Одно одобрение владельца охватывает все ноды. План показывает отпечаток ключа, недоверенный комментарий и ноды, где ключ уже есть (будут пропущены); результат для каждой ноды: added, already_present или failed с кодом ошибки. Закрытые ключи не принимаются. всегда (step-up)
node_server_key_remove Админ План: node и key — key_id из node_server_keys_list (или целый SHA256-отпечаток); применение: только confirm_token. Ключ панели можно удалить, только если панель сначала проверит сохранённый пароль. всегда

relay_apply для create и enable держит порядок самой панели: создаёт ретрансляцию (выключенной), проверяет плечо, включает её, а затем панель проверяет путь снаружи. Ретрансляция, не прошедшая проверку, остаётся выключенной, а применение завершается ошибкой с этапом (leg или path) и его кодом; при переносе порта включённой ретрансляции путь проверяется заново, и при провале ретрансляция выключается. Второй сервер появляется в подписках или пропадает из них при их следующем обновлении. См. Ретрансляция.

Каждый _plan принимает ещё reason: слова самого агента, не длиннее 300 символов, владелец видит их как цитату. Ни один инструмент не принимает и не возвращает пароль сервера: на экране одобрения владелец выбирает ключ панели или вводит пароль для установки, а при смене пароля новый генерирует сама панель. user_create никогда не возвращает ссылку подписки нового пользователя: её копирует владелец в админке.

os_rollout_start_plan поддерживает от одной до 20 нод и требует одобрения владельца: до него ничего не устанавливается и не перезагружается. Канарейка — нода с наименьшим числом людей онлайн, затем с наименьшим числом inbound; следующие ноды запускаются пакетами только после прохождения проверки предыдущего пакета. Причины busy, apt_lock, too_soon и reboot_limit ждут и повторяются до двух часов, затем шаг пропускается с try_later; жёсткие блокировки пропускаются сразу. При планировании одной занятой ноды возвращается os_blocked: reason=node_busy; в многоузловом плане нода ожидает повторной попытки. Реальная ошибка ставит раскатку на паузу. Продолжение повторяет неудачный шаг один раз либо пропускает его с skip_failed; отмена не прерывает задание, уже выполняющееся на ноде. При перезагрузке люди на ноде отключаются примерно на две минуты. Проверки ноды нельзя обойти. Сервер панели вне области этой функции.

rollout_start_plan запускает поэтапное обновление от одной до 20 выбранных нод. У каждой должен быть поддерживаемый онлайн-агент старше подписанного пакета (устаревший, с неудачным обновлением или откатившийся); новое обновление нельзя начать, пока другое выполняется или приостановлено. Панель ставит канарейкой ноду с меньшим числом людей онлайн, затем учитывает число входящих профилей; размер пакета равен одной ноде для набора меньше пяти и двум в остальных случаях. План закрепляет точный набор нод и версию/сборку подписанного пакета; если выбранная нода или пакет изменятся до применения, оно завершится ошибкой и понадобится новый план. node_update_schedule_plan сохраняет будущее обновление одной ноды после одобрения владельцем; при планировании нода может быть отключена, а новое расписание заменяет прежнее расписание ноды. Задание закреплено за подписанным релизом и фиксированным смещением UTC. Если в назначенное время нода отключена, панель ждёт её подключения ещё два часа, после чего задание помечается как пропущенное и само не начнётся; если подписанный пакет сменился, задание останется видимым и панель не подменит версию. Для отмены используйте node_update_schedule_cancel_plan. update_timezone влияет только на новые задания; у существующих остаются прежние момент и смещение. update_download_timeout меняет окно загрузки только для новых шагов: совместимые агенты получают его вместе с командой, старые сохраняют встроенный лимит, а уже начатый шаг оставляет окно, зафиксированное при отправке.

subscription_app_upsert и subscription_app_remove меняют одно приложение на странице, которую видит каждый пользователь; приложение ищется по платформе и названию без учёта регистра (если у двух приложений одной платформы одно название, план отклоняется: такие меняйте в админке). Новое приложение встаёт в конец списка. Значения проверяются так же, как при сохранении в Подписки → Страница пользователя: ссылка на скачивание — http(s), шаблон ссылки «добавить» начинается со схемы самого приложения (happ://add/{url}, myclient://add?url={url_enc}&name={name_enc}) или с http(s), но никогда не с javascript:, data: и подобных, только известные подстановки, не больше 30 приложений; сверх того в тексте агента не должно быть невидимых символов форматирования. План читает настройки целиком и запоминает их состояние; если до применения кто-то сохранит настройки подписок, применение откажет с «the subscription settings changed after the plan» и ничего не перезапишет: сделайте новый план. В subscription_settings_get и в копии плана у агента строки запроса и длинные сегменты пути ссылок показаны как [redacted], как в любом результате; карточка одобрения у владельца показывает каждое значение полностью.

Telegram-прокси — один из трёх переключателей в apps у user_create и user_update. Пропущенное поле сохраняет значение пользователя, поэтому {"apps": {"telegram": true}} меняет только Telegram. Включение создаёт ключ Telegram человека, выключение отзывает его; в плане Telegram-прокси назван среди приложений. Хотя бы один из happ и amnezia должен остаться включённым: Telegram идёт в дополнение. Инструмента для самого ключа нет, и ни один инструмент не возвращает ссылки tg://proxy: перевыпуск и отзыв ключа и чтение ссылок делает владелец в админке (MTProto).

Приложение Mistgate — четвёртое поле apps (mistgate, по умолчанию включено). Оно работает, только пока включён happ. В плане оно названо отдельным фактом app_mistgate, а одобрение нужно такое же, как для любого другого изменения пользователя. client_api_settings теперь ещё читает, у скольких людей приложение включено и сколько устройств подключено по ключу (people, people_on, devices).

План и применение#

Некоторые временные отказы до начала каких-либо действий оставляют план в статусе planned или approved до первоначального срока истечения; ответ содержит busy, код причины и время, через которое можно повторить тот же confirm_token. Срок плана не продлевается, успешно применённый план нельзя применить повторно, а остальные ошибки по-прежнему переводят план в failed.

  1. Агент вызывает <tool>_plan с аргументами. Панель проверяет их, читает всё нужное и описывает изменение своими словами. Ничего не меняется. Результат:

    JSON
    {
      "plan_id": "pln_...",
      "summary": "Disable 5 users: their connections end and their devices are dropped from the nodes.",
      "facts": [{"key": "count", "value": "5"}, {"key": "users", "value": "...", "untrusted": true}],
      "needs_approval": true,
      "danger": ["bulk"],
      "expires_in_s": 600,
      "confirm_token": "cf_...",
      "next": "..."
    }
  2. Агент показывает план человеку, на которого работает, и ждёт его согласия. Если needs_approval равно true, он ждёт ещё и владельца.

  3. Агент вызывает <tool>_apply с confirm_token — единственным аргументом. Панель один раз выполняет сохранённые аргументы и отвечает plan_id, status: "applied" и строкой результата.

Токен подтверждения:

  • срабатывает один раз, в течение 10 минут, только для того API-токена, который сделал план, и только с этим инструментом;
  • не несёт аргументов: между планом и применением их не изменить;
  • повторное применение уже применённого плана возвращает тот же результат; токен подтверждения другого плана, инструмента или API-токена — просто «unknown confirm token».

Если применить нельзя, ответ объясняет почему: «waiting for the owner to approve plan pln_…; it expires at …», «rejected by the owner», «expired: make a new plan», «already running», «failed: …. Make a new plan.», «the token was revoked» или «timeout, outcome unknown: check before retrying».

Какие планы ждут владельца#

План ждёт владельца, если выполняется одно из условий (список danger):

Код Значение Инструменты
step_up Сама операция в админке просит свежего подтверждения. инструменты раскатки, os_rollout_start, os_rollout_cancel, os_rollout_pause, os_rollout_resume, node_rollback, node_update_schedule и его отмена, node_awg_backend, update_timezone, update_download_timeout, retention, node_install, node_server_password_rotate, node_server_key_add, node_server_keys_add, node_server_key_remove
fleet Меняет работу нод или убирает доступ пользователей. node_fix, node_decoy, node_ipv6, relay, group_update, инструменты раскатки, os_rollout_start, os_rollout_cancel, os_rollout_pause, os_rollout_resume, node_rollback, node_update_schedule и его отмена, node_install, node_server_password_rotate, node_server_key_add, node_server_keys_add, node_server_key_remove; все планы создания, обновления и развёртывания профилей
bulk Затрагивает несколько целей в одном плане или больше 3 пользователей сразу. массовые rollout_start и node_server_keys_add, user_disable, user_reset_traffic
user_change_limit С этим планом токен превысит часовой лимит изменений пользователей (10, см. «Ограничения»), поэтому план не отклоняется, а ждёт владельца. В карточке видно, сколько лимита использовано. user_disable, user_reset_traffic, user_update, device_revoke
traffic Гонит объёмный тестовый трафик между нодами. path_speed
user_page Меняет общую настройку подписки или данные, которые видят или получают пользователи. subscription_app_upsert, subscription_app_remove, subscription_rules_set, subscription_texts_set, subscription_link_limits_set, subscription_page_set, dns_settings_set, dns_preset_create, dns_preset_update, dns_preset_delete, node_update
schedule Панель будет сама, раз за разом, запускать инструменты или ассистента. task_create, task_update, task_delete

group_update относится к fleet, потому что смена профилей или отключённых нод группы может изменить доступ её участников. group_delete отклоняется, пока в группе есть люди. node_update ограничен метаданными и переключателями, которые видны в подписке; все его изменения требуют одобрения владельца, потому что API обновления ноды принимает и поля, меняющие работу ноды, которые этот инструмент не открывает.

Перед сохранением плана проверяются настройки и новые ноды. Каждое изменение профиля ждёт одобрения владельца в админке. profile_update и profile_deploy используют версию профиля, прочитанную при создании плана; если до применения версия изменилась, вернётся changed_since_plan. При размещении ссылки на группы объединяются с их текущим состоянием; если следующий шаг завершится ошибкой, ответ сообщит уже выполненные действия. При ошибке profile_create удаляет созданный профиль и входящие подключения; удаление профиля также удаляет ссылки на группы. Секреты не попадают в ответы чтения, факты и аргументы плана или записи аудита.

Где владелец одобряет#

Такой план появляется в ИИ → Ждут вас, а в админке загорается значок; если владелец привязал Telegram, панель ещё и присылает сообщение, что план ждёт, со ссылкой туда (решение принимается только в админке: см. Алерты в Telegram). Владелец видит изменение словами панели, пометки об опасности, причину от агента (с пометкой «Написана агентом, панель её не проверяла.») и оставшееся время, затем выбирает:

  • Одобрить — ещё раз спросит passkey или код владельца. После этого применение агента пройдёт — только для этого плана.
  • Отклонить — применение агента вернёт «rejected by the owner».

В node_install карточка одобрения показывает SHA-256 отпечаток host key, который прочитала сама панель, и тип ключа (в копии плана у агента отпечаток скрыт, как любое значение, похожее на ключ). Владелец сверяет его с доверенной копией, ставит отметку подтверждения и выбирает, как панель будет входить: Ключ панели (карточка показывает открытый ключ панели, он уже должен быть на сервере; выбор появляется, когда в плане назван ключ панели) или Пароль (владелец вводит там же SSH-пароль сервера; установка тогда по умолчанию добавляет на сервер и ключ панели, и дальше панель входит по ключу). Пока host key не подтверждён и, для пароля, пароль не введён, кнопка Одобрить недоступна. Панель запечатывает выбор и введённый пароль за этим планом, и применение агента, в котором только confirm_token, один раз запускает установку с ним и ровно с подтверждённым ключом. Пароль не проходит ни через агента, ни через его переписку, ни через провайдера модели. Смена пароля тоже требует одобрения владельца: новый пароль генерирует панель и никогда его не возвращает.

Токен никогда не может подтвердить собственный план. Нерешённые планы истекают через 10 минут после создания. Недавние решения хранят историю с итогом: выполнено, ошибка, истекло, отменено (токен отозвали) и так далее. Агенту не стоит проверять статус чаще раза в 30 секунд.

Пример: добавить kl!ck для Windows и macOS#

kl!ck — десктопное приложение, которое рекомендует Mistgate. Чтобы поставить его на страницу пользователя для Windows и macOS, агент с профилем «Оператор» делает так. План запоминает состояние всех настроек, поэтому каждый следующий план делайте после применения предыдущего.

  1. subscription_settings_get: прочитать текущие приложения, чтобы знать, что там уже есть и какие записи Happ рекомендованы.

  2. subscription_app_upsert_plan для Windows:

    JSON
    {
      "platform": "windows",
      "name": "kl!ck",
      "kind": "happ",
      "download_url": "https://github.com/vbu00/klick/releases/latest",
      "add_link_template": "klick://add?url={url_enc}&name={name_enc}",
      "recommended": true,
      "reason": "kl!ck is the recommended desktop app"
    }

    У плана needs_approval и пометка user_page. Покажите его, попросите владельца одобрить в ИИ → Ждут вас, затем вызовите subscription_app_upsert_apply с confirm_token.

  3. То же для macOS: те же аргументы с "platform": "macos".

  4. Чтобы kl!ck шёл первым, снимите значок с Happ на обеих платформах, по одному плану на каждую: {"platform": "windows", "name": "Happ", "recommended": false, "reason": "kl!ck leads on the desktop"}, затем то же с "macos". Для уже существующего приложения указывают только меняемые поля.

kind: "happ" означает «по ссылке подписки», какое бы приложение её ни открывало. Ссылка на скачивание — страница релизов: в именах файлов стоит версия, а сборки для Windows и macOS выходят отдельно. Ссылка в одно касание работает только в сборках kl!ck новее 0.4.0; на старых человек пользуется Скопировать ссылку на странице. Новое приложение встаёт в конец списка; рекомендованное идёт первым на своей платформе, где бы оно ни стояло. Результат потом показывает subscription_settings_get (строки запросов в ссылках для агента выглядят как [redacted]).

Недоверенные данные в результатах#

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

Панель защищает и агента, и вас:

  • Текст из данных очищается: управляющие символы, переводы строк и невидимые символы форматирования убираются, длинные значения обрезаются.
  • Сводка плана никогда не содержит текста из данных; такие значения идут отдельными фактами с пометкой untrusted, а владелец видит их в кавычках.
  • То, что одобряет владелец, показывается целиком. Длинное значение (текст задачи, список резолверов, текст страницы пользователя) приходит нумерованными фактами; новое значение, которое нельзя показать как есть (скрытый или двунаправленный управляющий символ либо текст, который изменил бы редактор секретов: ключ, ссылка с токеном), отклоняется при составлении плана с указанием поля. Текущее значение поля показывается с вымаранными секретами и никогда не мешает изменению.
  • Последний проход по каждому результату заменяет всё, что похоже на секрет: API-токены, ссылки подключения (hysteria2://… и подобные), конфигурации туннелей, ключевой материал, query-строки URL и длинные сегменты пути URL (секретный префикс, токен подписки) и голые 32-байтовые ключи.

Чего агент не получает никогда#

  • Ссылок подписки и паролей страниц пользователей.
  • Ключа Telegram-прокси и его ссылок tg://proxy.
  • Ключей и конфигураций устройств, аккаунтов и ключей WARP, секретов профилей.
  • Паролей серверов: ни SSH-пароля для установки, ни нового пароля после смены.
  • Адресов нод и отпечатков сертификатов. Исключение — сохранённые SSH-адрес и логин, которые токену профиля «Админ» показывают node_server_access_list и планы node_install и смены пароля.
  • Ничего о токенах, одобрениях, сессиях и passkey.
  • Журнала аудита, если у токена не профиль «Админ».

Аудит#

Каждая процедура, которую вызывает инструмент, пишется в журнал аудита от имени «токен MCP <имя>» с источником MCP. Планы и применения добавляют свои строки: «составил(а) план изменения: <инструмент>» и «выполнил(а) запланированное изменение: <инструмент>»; решения владельца выглядят как «одобрил(а) изменение» или «отклонил(а) изменение». Настройки → Аудит отбирает их по источнику MCP.

Править страницу на GitHub