AgentBridge (Русский)

§1 Обзор

Что такое AgentBridge?

Когда агент IDE (например, GitHub Copilot, Cursor или Claude Code) выполняет вызов API, он подключается напрямую к вышестоящему поставщику ИИ (OpenAI, Anthropic и т. д.). AgentBridge прозрачно перехватывает это подключение на уровне TLS — без необходимости изменять конфигурацию агента — и перенаправляет запрос через OmniRoute.

Это позволяет:

• Перенаправлять любой агент к любому поставщику: Copilot обращается к OpenAI? Перенаправьте его к Anthropic Claude, Gemini или любому из 352 поставщиков OmniRoute.
• Применять сопоставления моделей: gemini-3-flash → claude-sonnet-4.7 прозрачно на уровне обработчика.
• Наблюдать за всем трафиком агентов: каждый перехваченный запрос публикуется в инспекторе трафика.
• Применять механизмы отказоустойчивости OmniRoute: комбинированная маршрутизация, автоматические выключатели, резервные варианты и учёт затрат также работают для трафика агентов IDE.

Позиционирование относительно рынка

Возможность	9router	anti-api	llm-interceptor	OmniRoute AgentBridge
Antigravity	✓	✓	—	✓
GitHub Copilot	✓	✓	—	✓
Kiro (AWS)	✓	✓	—	✓
OpenAI Codex	—	✓	—	✓
Cursor IDE	✓	✓	—	✓
Zed Industries	—	✓	—	✓
Claude Code	—	—	✓	✓
Open Code	—	—	✓	✓
Trae	—	—	—	🔍 Исследуется
Интерфейс панели управления	✓	✗	✗	✓
Инспектор трафика	✗	✗	✓	✓
Маршрутизация OmniRoute	✗	✗	✗	✓
Интерфейс сопоставления моделей	✗	✗	✗	✓
Список обхода	✗	✗	✓	✓
Сертификат вышестоящего УЦ	✗	✗	✓	✓

---

§2 Архитектура

2.1 Обзор компонентов

Агент IDE (VS Code / Cursor / и т. д.)
    │  HTTPS (порт 443)
    ▼
/etc/hosts — 127.0.0.1 api.githubcopilot.com   ← перенаправление DNS
    │
    ▼
src/mitm/server.cjs  (порт 443, дочерний процесс CJS)
    │  определяет целевой узел по SNI из заголовка Host
    │  генерирует отдельный TLS-сертификат для каждого SNI, подписанный CA AgentBridge
    ├── Совпадение со списком обхода? → сквозная передача TCP (без расшифровки)
    ├── Совпадение с целевым узлом? → fetch → маршрутизатор OmniRoute (порт 20128)
    │       └── handler.intercept() — TypeScript
    │               ├── maskSecrets() для тела/заголовков запроса
    │               ├── TrafficBuffer.push() — публикует в Инспектор трафика
    │               └── fetchRouter() → /v1/chat/completions
    └── Нет совпадения? → сквозная передача TCP (без расшифровки)

2.2 MITM-сервер (src/mitm/server.cjs)

Основной MITM-сервер работает как дочерний процесс Node.js CJS (чтобы не переписывать существующую кодовую базу CJS). Он:

• Прослушивает порт 443 (требуются привилегии либо authbind/setcap)
• Принимает туннели CONNECT от ОС (посредством перенаправления DNS через /etc/hosts)
• Генерирует отдельные TLS-сертификаты для каждого SNI, подписанные CA AgentBridge (DATA_DIR/mitm/ca.crt)
• Определяет целевой агент по заголовку Host через реестр targets/index.ts
• Передаёт запросы на уровень обработчиков TypeScript по HTTP на http://127.0.0.1:20128

TARGET_HOSTS загружается из DATA_DIR/mitm/targets.json (файл записывается targets/index.ts при запуске), что позволяет динамически обновлять список без перезапуска CJS-сервера.

Модель корневого CA (#6684). Описанная выше модель с отдельным сертификатом для каждого SNI, подписанным CA, представляет собой сохраняемую модель корневого CA, добавленную в #6684 (src/mitm/cert/rootCa.ts + src/mitm/_internal/rootCaShim.cjs, с повторным использованием криптографической реализации CA/листовых сертификатов, уже проверенной для TPROXY в src/mitm/tproxy/dynamicCert.ts) — она заменяет прежний единственный статический самоподписанный листовой сертификат (src/mitm/cert/generate.ts, область действия которого по-прежнему ограничена только узлами antigravity), на наличие которого указывает простая пара server.crt/server.key на диске. Поведение при миграции: новая установка (без существующего server.crt) автоматически получает модель корневого CA; установка, которая уже доверяет старому статическому листовому сертификату, продолжает использовать его, пока оператор не задаст MITM_ROOT_CA_ENABLED=true и не перезапустит мост (src/mitm/cert/migration.ts содержит чистую функцию принятия решения — доверенный MITM CA, способный подписать листовой сертификат для любого узла, существенно мощнее прежнего листового сертификата с фиксированным SAN, поэтому для уже доверенной установки переключение никогда не выполняется незаметно). Сертификат CA устанавливается в тот же слот хранилища доверия omniroute-mitm.crt, который использовался старым листовым сертификатом (cert/install.ts::installCaCert), — очистка двойного доверия не требуется.

2.3 Базовый обработчик (src/mitm/handlers/base.ts)

Все обработчики агентов наследуют MitmHandlerBase:

export abstract class MitmHandlerBase {
  abstract readonly agentId: AgentId;

  abstract intercept(
    req: IncomingMessage,
    res: ServerResponse,
    body: Buffer,
    mappedModel: string
  ): Promise<void>;

  // Защищённые вспомогательные методы: fetchRouter, pipeSSE, hookBufferStart, hookBufferUpdate
}

Каждый обработчик вызывает hookBufferStart() перед проксированием и hookBufferUpdate() после завершения. Эти методы добавляют записи InterceptedRequest в globalTrafficBuffer (см. Инспектор трафика, §4).

2.4 Реестр целевых узлов (src/mitm/targets/)

Для каждого агента предусмотрен декларативный файл целевого узла:

src/mitm/targets/copilot.ts

export const COPILOT_TARGET: MitmTarget = {
  id: "copilot",
  name: "GitHub Copilot",
  hosts: ["api.githubcopilot.com", "copilot-proxy.githubusercontent.com"],
  port: 443,
  endpointPatterns: ["/chat/completions", "/v1/chat/completions"],
  defaultModels: [{ id: "gpt-4o", name: "GPT-4o", alias: "gpt-4o" }],
  handler: () => import("../handlers/copilot"),
  riskNoticeKey: "providers.riskNotice.oauth",
};

Реестр (targets/index.ts) экспортирует ALL_TARGETS и создаёт DATA_DIR/mitm/targets.json при запуске.

2.5 Сквозная передача и список обхода (src/mitm/passthrough.ts)

Список обхода (проверяется первым и имеет приоритет над совпадением с целевым узлом):

• Шаблоны по умолчанию: банковские узлы, .gov., поставщики OAuth/SSO (Okta, Auth0) и т. д.
• Пользовательские шаблоны: хранятся в таблице БД agent_bridge_bypass
• Обходные узлы получают прозрачный TCP-туннель — TLS никогда не расшифровывается

Сквозная передача по умолчанию (нет совпадения с целевым узлом и узел отсутствует в списке обхода):

• Также получает TCP-туннель — соединения никогда не разрываются
• Не позволяет AgentBridge нарушать работу общего системного HTTPS-трафика

Приоритет маршрутизации:

список обхода → совпадение с целевым узлом → сквозная передача

2.6 Сертификат вышестоящего CA (src/mitm/upstreamTrust.ts)

Для корпоративных сетевых сред с пользовательским CA:

AGENTBRIDGE_UPSTREAM_CA_CERT=/path/to/corporate-ca.pem

Если переменная задана, глобальный диспетчер undici настраивается с дополнительным сертификатом CA, позволяя AgentBridge обращаться к вышестоящим поставщикам через корпоративные прокси-серверы терминации TLS.

2.7 Маскирование секретов (src/mitm/maskSecrets.ts)

Независимый сканер, реализованный методом «чистой комнаты», применяется к телам запросов и заголовкам с учётными данными до их попадания в буфер Инспектора трафика или любой журнал. Он выполняет один линейный проход:

• Токены с префиксами sk- / ak- / pk- (в стиле OpenAI/Anthropic)
• Учётные данные RFC 6750 Authorization: Bearer <token> с приоритетом полного токена
• Универсальные длинные непрозрачные токены (≥40 символов), включая формы с точками и дополнением

sanitizeHeaders() переводит сохраняемые имена в нижний регистр, детерминированно объединяет значения массивов, удаляет общий список запрещённых промежуточных/структурных заголовков (включая аутентификацию прокси), полностью скрывает cookie и set-cookie и передаёт значения учётных данных сканеру.

---

§3 Настройка

3.1 Запуск и остановка MITM-сервера

Используйте карточку AgentBridge Server по адресу /dashboard/tools/agent-bridge:

Действие	Описание
Запустить сервер	Запускает src/mitm/server.cjs на порту 443
Остановить сервер	Корректно завершает дочерний процесс
Перезапустить сервер	Останавливает и запускает сервер (применяет изменения целей)
Доверять сертификату	Устанавливает DATA_DIR/mitm/ca.crt в хранилище доверия ОС
Скачать сертификат	Скачивает ca.crt для установки вручную
Пересоздать сертификат	Создаёт новую пару ключей CA (все существующие сертификаты агентов становятся недействительными)

3.2 Добавление сертификата в доверенные

Сертификат CA AgentBridge должен быть добавлен в доверенные на уровне ОС, прежде чем IDE смогут принять MITM-соединение.

Linux (NSS — Chrome/Firefox):

certutil -A -d sql:$HOME/.pki/nssdb -n "OmniRoute AgentBridge" -t CT,, -i ~/.omniroute/mitm/ca.crt

macOS (Связка ключей):

sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain ~/.omniroute/mitm/ca.crt

Windows (certmgr):

certutil -addstore -f Root $env:USERPROFILE\.omniroute\mitm\ca.crt

Также можно воспользоваться кнопкой «Доверять сертификату» на панели управления (она запускает соответствующую команду для вашей ОС и при необходимости выводит запрос sudo).

IDE на базе Electron игнорируют хранилище доверия ОС (NODE_EXTRA_CA_CERTS)

Некоторые IDE — в частности Antigravity IDE, а также другие приложения на базе Electron / VS Code — включают собственную среду выполнения Node.js, которая не обращается к хранилищу доверия ОС при исходящих запросах fetch/HTTPS. Добавления CA в доверенные на уровне ОС/NSS достаточно для нативного бэкенда IDE (например, языкового сервера на Go, использующего набор CA операционной системы), но фронтенд Electron по-прежнему не сможет установить TLS-соединение — это проявляется как выход из учётной записи в приложении или сообщение «ошибка подключения», даже если журнал MITM показывает, что начальные запросы бэкенда возвращают 200. Необходимо выполнить два шага, и важны оба:

1. Явно укажите среде выполнения путь к CA:

   export NODE_EXTRA_CA_CERTS=/path/to/omniroute-agentbridge-ca.crt

2. Запустите IDE из этой командной оболочки. При запуске через значок на рабочем столе / Dock / меню «Пуск» экспортированные переменные оболочки не наследуются, а ~/.config/environment.d/*.conf применяется только после нового входа в графическую сессию. Сначала полностью закройте IDE — из-за блокировки единственного экземпляра Electron повторный запуск лишь переводит уже запущенный процесс на передний план, и новое окружение игнорируется.

Описанное выше добавление в доверенные на уровне ОС и NSS по-прежнему необходимо (сетевой стек Chromium, используемый некоторыми потоками аутентификации, читает пользовательское хранилище NSS и имеет собственные статические закрепления сертификатов для *.googleapis.com, которые переопределяются локально доверенным CA). NODE_EXTRA_CA_CERTS дополнительно охватывает путь Node fetch.

3.3 Маршрутизация DNS

Для каждого агента, трафик которого требуется перехватывать, его хосты API должны разрешаться в 127.0.0.1. AgentBridge автоматически управляет записями /etc/hosts, когда вы включаете или отключаете DNS для агента в мастере настройки.

Пример записей /etc/hosts для GitHub Copilot:

127.0.0.1 api.githubcopilot.com
127.0.0.1 copilot-proxy.githubusercontent.com

3.4 Сопоставление моделей

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

Исходная модель (нативная для агента)	Целевая модель (OmniRoute)
gpt-4o	claude-sonnet-4.7
* (подстановочный знак)	claude-haiku-4.7

Подстановочный знак * сопоставляет любую нераспознанную модель с указанной целевой моделью. Настройки сохраняются в таблице agent_bridge_mappings.

Совет — определите реальные идентификаторы моделей агента. IDE может отправлять названия моделей, которые отличаются от меток в пользовательском интерфейсе и изменяются между основными версиями. Например, Antigravity 2 передаёт gemini-3.1-pro-low, gemini-pro-agent и gemini-3.1-flash-lite — а не gemini-2.5-pro, указанную в более старой документации. Отправьте одно сообщение в чате при отсутствии подходящего сопоставления: MITM запишет в журнал точное входящее значение model: и пропустит запрос дальше. Сопоставьте это буквальное значение, после чего следующий запрос будет перехвачен и направлен к выбранной целевой модели.

3.5 Уведомление о рисках

AgentBridge перехватывает учётные данные (токены OAuth, ключи API), которые IDE использует для аутентификации у вышестоящих провайдеров. Они маскируются перед записью в журнал (см. §2.7), но доступны MITM-слою OmniRoute. При первой активации каждого агента отображается закрываемое модальное окно с уведомлением о рисках.

3.6 Обслуживание и диагностика

На панели управления доступна карточка Обслуживание и диагностика (AgentBridgeMaintenanceCard, в src/app/(dashboard)/dashboard/tools/agent-bridge/components/), которая предоставляет доступ к служебным маршрутам MITM, ранее не имевшим пользовательского интерфейса. Её подзаголовок: «Выполняйте самопроверку конвейера перехвата, отменяйте оставшиеся системные изменения и переносите конфигурацию между компьютерами». Клиентские вспомогательные функции карточки находятся в src/lib/inspector/agentBridgeMaintenanceApi.ts.

Кнопка	Маршрут	Что делает
Диагностика	GET /api/tools/agent-bridge/diagnose	Запускает самопроверку конвейера перехвата и отображает отчёт по каждой проверке (✓/✗ + рекомендация по устранению проблемы).
Исправить	POST /api/tools/agent-bridge/repair	Устраняет оставшееся после сбоя или SIGKILL состояние MITM в системе (подменённые записи DNS, корневой ЦС, системный прокси). Операция идемпотентна — если состояние чистое, возвращается «Исправлять нечего».
Удалить ЦС	DELETE /api/tools/agent-bridge/cert	Отзывает доверие и удаляет корневой ЦС MITM из системного хранилища доверенных сертификатов (явно, идемпотентно). Отображается только тогда, когда ЦС в настоящее время является доверенным; требует встроенного подтверждения «Удалить ЦС?».
Экспорт конфигурации	GET /api/tools/agent-bridge/config	Загружает переносимую конфигурацию в формате JSON (см. §3.7).
Импорт конфигурации	POST /api/tools/agent-bridge/config	Загружает ранее экспортированную конфигурацию в формате JSON (см. §3.7).

Диагностические проверки (summarizeDiagnostics() в src/mitm/inspector/diagnostics.ts). Маршрут запускает для каждой проверки пробу с побочными эффектами и передаёт логические значения чистой функции формирования сводки; возвращаются единый вердикт healthy и рекомендация для каждой обнаруженной проблемы:

Название проверки	Что она проверяет	Рекомендация при сбое
server-running	Процесс сервера MITM активен	«Сервер MITM не запущен. Запустите его на вкладке AgentBridge».
server-reachable	Сервер MITM принимает подключения на своём порте (TCP-проверка)	«Сервер MITM не принимает подключения на своём порте. Убедитесь, что порт свободен и у вас есть права на его привязку».
cert-exists	Сертификат MITM создан на диске	«Сертификат MITM ещё не создан. Создайте его на вкладке AgentBridge».
cert-trusted	Корневой ЦС MITM находится в системном хранилище доверенных сертификатов	«Системное хранилище не доверяет корневому ЦС MITM, поэтому перехват TLS завершится сбоем. Добавьте сертификат в доверенные на вкладке AgentBridge».
dns-configured	Целевые имена хостов подменены в /etc/hosts	«Целевые имена хостов не подменены в /etc/hosts, поэтому трафик не достигает прокси. Включите DNS для агентов, трафик которых нужно перехватывать».

Баннер оставшегося состояния: когда страница обнаруживает состояние, оставшееся после сбоя (подмена DNS / ЦС / системный прокси), на карточке отображается янтарный баннер — «Предыдущий сеанс оставил после себя системное состояние (подмена DNS, ЦС или системный прокси). Запустите исправление, чтобы очистить его». — и выделяется кнопка Исправить. Repair — это аналог флага --cleanup ProxyBridge на уровне приложения (он делегирует выполнение функции repairMitm() в src/mitm/manager.ts).

Корневой ЦС MITM остаётся установленным между остановкой и запуском, чтобы избежать повторных запросов sudo (аналогично поведению mitmproxy/Charles), поэтому его удаление выполняется явным действием Удалить ЦС, а не автоматически при остановке.

3.7 Импорт и экспорт переносимой конфигурации

AgentBridge может сериализовать настраиваемое оператором состояние в версионированный объект JSON, чтобы конфигурацию можно было воспроизвести на разных машинах. Сериализатор находится в src/lib/inspector/configPortability.ts (exportConfig() / importConfig()), а проверка выполняется с помощью AgentBridgeConfigSchema.

Экспорт содержит ровно три компонента (встроенные значения по умолчанию намеренно НЕ экспортируются, поэтому импорт никогда не приводит к их дублированию или конфликту с ними):

Поле	Источник	Примечания
bypassPatterns	пользовательские шаблоны обхода (agent_bridge_bypass)	шаблоны по умолчанию для банков, государственных сайтов и okta исключены
customHosts	пользовательские хосты Traffic Inspector (inspector_custom_hosts)	каждый: { host, kind: "llm"|"app"|"custom", label? }
agentMappings	сопоставления моделей для каждого агента (agent_bridge_mappings)	{ [agentId]: [{ source, target }] } для каждого агента, имеющего сопоставления

// GET /api/tools/agent-bridge/config
{
  "version": 1,
  "bypassPatterns": ["*.internal.example.com"],
  "customHosts": [{ "host": "api.example.com", "kind": "llm", "label": null }],
  "agentMappings": {
    "copilot": [{ "source": "gpt-4o", "target": "claude-sonnet-4.7" }],
  },
}

Поведение при импорте (POST /api/tools/agent-bridge/config): шаблоны обхода и сопоставления для каждого агента заменяются целиком; пользовательские хосты добавляются идемпотентно (INSERT OR IGNORE). В ответе указывается, сколько элементов каждого типа было применено:

{ "ok": true, "bypassPatterns": 1, "customHosts": 1, "agents": 1 }

Что НЕ входит в конфигурацию: состояние работы сервера, пути к сертификатам, состояние DNS для отдельных агентов, путь к вышестоящему центру сертификации и настройки TPROXY — это состояние хоста/среды выполнения, а не переносимые параметры.

---

§4 Справочная информация по агентам

#	Агент	Статус	Перехватываемые хосты	Тип аутентификации
1	Antigravity	✅ Поддерживается	daily-cloudcode-pa.googleapis.com, cloudcode-pa.googleapis.com	Firebase OAuth
2	Kiro (AWS)	✅ Поддерживается	prod.kiro.aws, dev.kiro.aws	AWS SigV4
3	GitHub Copilot	✅ Поддерживается	api.githubcopilot.com, copilot-proxy.githubusercontent.com	GitHub OAuth
4	OpenAI Codex	✅ Поддерживается	api.openai.com (пути Codex), chatgpt.com	Ключ OpenAI
5	Cursor IDE	✅ Поддерживается	api2.cursor.sh, api.cursor.sh	Cursor OAuth
6	Zed Industries	✅ Поддерживается	api.zed.dev, llm.zed.dev	Zed OAuth
7	Claude Code	✅ Поддерживается	api.anthropic.com (по желанию)	Ключ Anthropic
8	Open Code	✅ Поддерживается	openrouter.ai, api.openai.com (пути zen)	Ключ API
9	Trae	🔍 Исследуется	Уточняется — см. §8	Уточняется

Шаги мастера настройки (для каждого агента)

Карточка каждого агента содержит трёхэтапный мастер настройки:

1. Проверка предварительных требований — Сервер запущен? Сертификат является доверенным? IDE установлена (автоматическое обнаружение)?
2. Включение DNS — Добавляет записи в /etc/hosts (требуется sudo). Показывает, какие именно строки будут добавлены.
3. Сопоставление моделей — Необязательная таблица сопоставления моделей. Поддерживаются подстановочные символы.

Обнаружение агентов

Для агентов 1–8 AgentBridge пытается автоматически обнаружить установленную IDE:

export async function detectAgent(agentId: AgentId): Promise<DetectionResult>;
// Возвращает: { installed: boolean, version?: string, path?: string }

Для обнаружения используются пути и проверки исполняемых файлов, специфичные для ОС (например, code --list-extensions | grep github.copilot для Copilot, ~/.config/antigravity/ для Antigravity).

---

§5 Безопасность

Применяемые строгие правила

Правило	Применение
#12 sanitizeErrorMessage	Все ошибки обработчиков очищаются перед отправкой ответа или добавлением в буфер
#13 Передача окружения в shell	При изменении /etc/hosts используется параметр env — без строковой интерполяции путей
#15 + #17 isLocalOnlyPath()	/api/tools/agent-bridge/ имеет категории LOCAL_ONLY + SPAWN_CAPABLE — loopback проверяется до аутентификации

Список обхода для конфиденциальных хостов

Список обхода гарантирует, что трафик финансовых учреждений, поставщиков OAuth/SSO и других конфиденциальных хостов никогда не расшифровывается. Их TLS-трафик проходит через прозрачный TCP-туннель — OmniRoute никогда не видит открытый текст.

Стандартные шаблоны обхода включают:

• *.bank.*, *.gov.* (финансовые/государственные ресурсы)
• *.okta.com, *.auth0.com, *.microsoft.com (SSO/управление идентификацией)
• *.apple.com, *.icloud.com (системные службы Apple)

Добавленные пользователем шаблоны обхода хранятся в таблице agent_bridge_bypass и имеют приоритет над всеми остальными правилами.

Маскирование секретов

Применяется maskSecrets() из src/mitm/maskSecrets.ts:

• К каждому телу запроса перед TrafficBuffer.push()
• К каждому заголовку перед журналированием или широковещательной передачей

Шаблоны: токены с префиксами sk-/ak-/pk-, токены Bearer и универсальные токены длиной ≥40 символов.

Сертификат вышестоящего центра сертификации

Если задана переменная AGENTBRIDGE_UPSTREAM_CA_CERT, файл считывается при запуске. Если путь существует, но файл невозможно прочитать, AgentBridge записывает понятную ошибку в журнал и отказывается запускаться (это предотвращает скрытые сбои TLS в корпоративных средах).

Известные ограничения

• Для порта 443 требуются привилегии: в Linux для бинарного файла Node необходимо выполнить setcap 'cap_net_bind_service=+ep' либо использовать запуск через authbind. Мастер настройки отображает инструкции для конкретной ОС.
• Требуется перезапуск IDE: после перенаправления DNS необходимо перезапустить IDE, чтобы новое разрешение хоста вступило в силу.
• Жёстко заданные токены OAuth: некоторые агенты (Kiro, Antigravity) хранят токены обновления OAuth локально. Для AgentBridge это прозрачно — он видит токен Bearer в каждом запросе, и этот токен маскируется перед журналированием.
• Для интерфейсов Electron требуется NODE_EXTRA_CA_CERTS: IDE, интерфейс которых работает во встроенной среде Node/Electron, игнорируют системное хранилище доверия ОС/NSS, поэтому их необходимо запускать из оболочки с заданной переменной NODE_EXTRA_CA_CERTS (см. §3.2). Признак отсутствия настройки: серверная часть IDE проходит аутентификацию (MITM показывает ответы 200), но пользовательский интерфейс остаётся в состоянии выхода из системы.
• Несколько установок одной IDE независимы друг от друга: системная установка (например, /usr/share/antigravity/antigravity) и локальная пользовательская установка «Full» (например, ~/AntigravityIDE_Full/antigravity-ide) являются отдельными процессами с собственными средами выполнения — каждую из них необходимо перезапустить с внедрённым сертификатом CA. Перед перезапуском определите по пути к бинарному файлу, какая именно установка запущена.
• Идентичность задаётся системным промптом агента, а не маршрутизируемой моделью: при переназначении модели агента на другого поставщика ответ по-прежнему заявляет исходную идентичность агента (например, Antigravity отвечает «Я работаю на базе Gemini»), поскольку IDE внедряет это в системный промпт. Проверяйте фактическую серверную часть в call_logs / proxy_logs (provider, model, target_format), а не спрашивайте модель, кем она является.

---

§6 Устранение неполадок

Конфликт порта 443

Если другой процесс уже прослушивает порт 443 (веб-сервер, VPN и т. д.):

lsof -i :443          # найти процесс
sudo fuser -k 443/tcp  # принудительно завершить (используйте с осторожностью)

В качестве альтернативы настройте непривилегированный порт в параметрах AgentBridge и задайте правила перенаправления iptables / pf.

Сертификат не является доверенным

Если после запуска AgentBridge IDE показывает ошибки TLS:

1. Убедитесь, что сертификат установлен: security find-certificate -c "OmniRoute AgentBridge" (macOS) или certutil -L -d sql:$HOME/.pki/nssdb (Linux/NSS)
2. Некоторые приложения используют собственное хранилище доверенных сертификатов (Firefox, Chrome в Linux). Снова выполните «Trust Cert» и проверьте хранилище сертификатов, используемое NSS/Firefox.
3. Перезапустите IDE после добавления сертификата в доверенные — активные сеансы TLS используют прежнее состояние доверия.

Выход из учётной записи IDE / «ошибка подключения» несмотря на доверенный ЦС

Симптом: после перенаправления DNS и добавления ЦС в доверенные IDE на базе Electron (например, Antigravity) открывается без выполненного входа или показывает ошибку аутентификации/подключения, хотя журнал MITM показывает, что начальные вызовы (loadCodeAssist, fetchAvailableModels, …) возвращают 200.

Причина: встроенная среда выполнения Node/Electron в IDE игнорирует системное хранилище доверенных сертификатов. Нативный бэкенд (языковой сервер на Go) доверяет системному ЦС и проходит аутентификацию, однако фронтенд Electron не доверяет ему, поэтому пользовательский интерфейс считает, что подключение отсутствует.

Исправление (оба шага): экспортируйте NODE_EXTRA_CA_CERTS=<ca.crt> и перезапустите IDE из той же оболочки, а не с помощью значка на рабочем столе. Сначала полностью завершите работу IDE — из-за блокировки единственного экземпляра Electron повторный запуск лишь переводит в фокус существующий процесс, а новое окружение игнорируется. См. §3.2. Это соответствует открытому отчёту в вышестоящем проекте, согласно которому отдельный агент работает через MITM, но вариант для IDE не работает при той же конфигурации.

Изменения DNS не применились

Убедитесь, что /etc/hosts был обновлён:

grep "omniroute\|127.0.0.1.*github\|127.0.0.1.*cursor" /etc/hosts

Очистите кэш DNS:

# macOS
sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder
# Linux (systemd-resolved)
sudo systemctl restart systemd-resolved
# Windows
ipconfig /flushdns

IDE не обнаружена

Автоматическое обнаружение использует стандартные пути установки. Если обнаружить IDE не удалось, но она установлена:

• Проверьте, не находится ли исполняемый файл IDE в нестандартном расположении
• Мастер настройки всё равно будет работать — сбой обнаружения означает лишь, что на индикаторе не будет показан путь установки

Ошибки обработчика (сбой запроса к вышестоящему сервису)

Если AgentBridge перехватывает запросы, но все они завершаются с ошибкой:

1. Убедитесь, что по адресу /dashboard/providers подключён хотя бы один провайдер
2. Проверьте журналы сервера OmniRoute: APP_LOG_LEVEL=debug в .env
3. Убедитесь, что OMNIROUTE_BASE_URL указывает на правильную конечную точку маршрутизатора (по умолчанию: http://127.0.0.1:20128)

---

§7 Справочник API

Все маршруты имеют атрибуты LOCAL_ONLY (доступ только через loopback-интерфейс, что проверяется до аутентификации) и SPAWN_CAPABLE. См. src/server/authz/routeGuard.ts.

Базовый путь: /api/tools/agent-bridge/

Метод	Путь	Описание
GET	/api/tools/agent-bridge/state	Глобальное состояние сервера + результаты обнаружения и статус каждого агента
GET	/api/tools/agent-bridge/agents	Список зарегистрированных агентов (id, имя, хосты, работоспособность, состояние)
GET	/api/tools/agent-bridge/agents/{id}	Состояние одного агента (целевая конфигурация + результаты обнаружения + сохранённое состояние)
PATCH	/api/tools/agent-bridge/agents/{id}	Обновить setup_completed для агента
GET	/api/tools/agent-bridge/agents/{id}/detect	Запустить проверку обнаружения агента (installed, version?, path?)
POST	/api/tools/agent-bridge/agents/{id}/dns	Включить/отключить DNS для агента ({enabled: boolean})
GET	/api/tools/agent-bridge/agents/{id}/mappings	Сопоставления моделей для агента
PUT	/api/tools/agent-bridge/agents/{id}/mappings	Заменить сопоставления моделей
POST	/api/tools/agent-bridge/server	Запустить/остановить/перезапустить сервер (action: "start"|"stop"|"restart"|"trust-cert"|"regenerate-cert")
GET	/api/tools/agent-bridge/cert	Статус сертификата (exists, trusted, path)
POST	/api/tools/agent-bridge/cert	Сделать корневой центр сертификации MITM доверенным (установить его)
DELETE	/api/tools/agent-bridge/cert	Отменить доверие к корневому центру сертификации MITM (удалить его) — идемпотентная операция (см. §3.6)
POST	/api/tools/agent-bridge/cert/regenerate	Пересоздать самоподписанный сертификат MITM
GET	/api/tools/agent-bridge/cert/download	Передать сертификат PEM потоком для скачивания
GET	/api/tools/agent-bridge/bypass	Получить список шаблонов обхода (default + user)
POST	/api/tools/agent-bridge/bypass	Полностью заменить пользовательские шаблоны обхода
DELETE	/api/tools/agent-bridge/bypass?pattern=...	Удалить один пользовательский шаблон обхода
GET	/api/tools/agent-bridge/diagnose	Самопроверка конвейера перехвата (см. §3.6)
POST	/api/tools/agent-bridge/repair	Отменить оставшиеся без владельца изменения системного состояния MITM (см. §3.6)
GET	/api/tools/agent-bridge/config	Экспортировать переносимую конфигурацию JSON (см. §3.7)
POST	/api/tools/agent-bridge/config	Импортировать переносимую конфигурацию JSON (см. §3.7)
GET	/api/tools/agent-bridge/upstream-ca	Получить настроенный путь к вышестоящему центру сертификации
POST	/api/tools/agent-bridge/upstream-ca	Проверить и сохранить путь к вышестоящему центру сертификации
POST	/api/tools/agent-bridge/upstream-ca/test	Только проверить (пробный запуск) путь к вышестоящему центру сертификации — без сохранения
GET / POST / DELETE	/api/tools/agent-bridge/tproxy	Режим перехвата TPROXY с прозрачным расшифрованием — см. docs/security/MITM-TPROXY-DECRYPT.md (git; не включается в /docs)

Полные схемы OpenAPI: docs/openapi.yaml → тег AgentBridge.

---

§8 План развития

Исследование Trae

Trae — относительно новый ИИ-ассистент для программирования. Перед реализацией обработчика необходимо:

1. Найти исполняемый файл или расширение в каталогах расширений VS Code / JetBrains либо отдельное приложение
2. Перехватить трафик с помощью mitmproxy, чтобы определить хосты API и структуру конечных точек
3. Определить механизм аутентификации
4. Принять решение о целесообразности реализации на основе условий использования и доступности сведений об API

До завершения исследования карточка Trae на панели управления отображает значок “Исследуется” со ссылкой “Сообщить о целесообразности”. Заглушка обработчика в src/mitm/handlers/trae.ts выбрасывает структурированную ошибку Not yet implemented.

Агенты в списке задач (требуется MITM — поддержка пользовательского базового URL отсутствует)

Следующие инструменты в текущих версиях не поддерживают пользовательские базовые URL, поэтому MITM является единственным способом перехвата. Оценка целесообразности еще не выполнена:

• Windsurf (Codeium/Cognition)
• Amp (Sourcegraph)
• Amazon Q / Kiro CLI (AWS Bedrock — отдельно от Kiro IDE)
• Cowork (настольное приложение Anthropic)

Примечание: GitHub Copilot CLI ≥v1.0.19 поддерживает COPILOT_PROVIDER_BASE_URL — для этого инструмента используйте прямую настройку вместо MITM.

---

Исходный код OmniRoute (a58000c7685f)