Сетевой прокси

AIKraft Agents может маршрутизировать весь сетевой трафик через HTTP или HTTPS-прокси. Это полезно для корпоративных сетей, требующих доступа через прокси, файрволов, блокирующих прямые подключения, или окружений, где требуется проверка сетевого трафика.

Конфигурация

Откройте Настройки → Сеть и настройте:

Настройки сохраняются в ~/.craft-agent/config.json в ключе networkProxy:

{
  "networkProxy": {
    "enabled": true,
    "httpProxy": "http://proxy.corp.com:8080",
    "httpsProxy": "http://proxy.corp.com:8080",
    "noProxy": "localhost,127.0.0.1,.internal.com"
  }
}

Изменения вступают в силу немедленно — перезапуск не требуется.

Как это работает

При включённом прокси AIKraft Agents маршрутизирует трафик на трёх уровнях:

1. Node.js (главный процесс) — Все вызовы fetch() (потоки OAuth, подключения к MCP-серверам, API-запросы) маршрутизируются через undici ProxyAgent, использующий HTTPS CONNECT-туннелирование для защищённых соединений.
2. Electron (браузерные окна) — Запросы браузерной панели и окна OAuth используют встроенную поддержку прокси в Chromium через session.setProxy().
3. Подпроцессы SDK — Подпроцесс Claude Code автоматически получает переменные окружения HTTP_PROXY, HTTPS_PROXY и NO_PROXY.

Аутентификация прокси

Для прокси, требующих аутентификации, включите учётные данные в URL:

http://username:password@proxy.corp.com:8080

Учётные данные прокси хранятся в открытом виде в config.json. Используйте конфигурацию прокси на уровне окружения, если ваша политика безопасности требует зашифрованного хранилища учётных данных.

Правила обхода прокси

Поле Без прокси принимает список правил обхода через запятую:

localhost и 127.0.0.1 не обходятся автоматически. Если ваша конфигурация требует прямого доступа к локальным сервисам (например, локальным MCP-серверам), добавьте их в список «Без прокси» явно.

TLS-перехватывающие прокси (корпоративные файрволы)

Многие корпоративные прокси выполняют проверку TLS, повторно подписывая HTTPS-трафик внутренним сертификатом ЦС. Это приводит к ошибкам fetch failed, так как Node.js по умолчанию не доверяет сертификату ЦС прокси.

Симптомы

• Вход через OAuth завершается ошибкой «fetch failed» или молча не открывает окно браузера
• Подключения к MCP-серверам не работают за корпоративной сетью, но работают в личных сетях
• Запросы браузерной панели работают нормально (Chromium использует системное хранилище сертификатов), но запросы, инициированные агентом, завершаются ошибкой

Решение

Установите переменную окружения NODE_EXTRA_CA_CERTS, указывающую на сертификат ЦС корпоративного прокси, перед запуском AIKraft Agents:

macOS

Однократный запуск из терминала:

NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem open -a "AIKraft Agents"

Постоянная настройка (все приложения, включая запуск из Dock/Spotlight):

Переменные в профиле оболочки (~/.zshrc) применяются только к терминальным сессиям. Чтобы установить переменные окружения для упакованных приложений, запущенных из Dock или Spotlight, используйте launchctl:

# Установить для текущей пользовательской сессии (сохраняется после перезагрузки на современном macOS)
launchctl setenv NODE_EXTRA_CA_CERTS /path/to/corporate-ca.pem

Затем перезапустите AIKraft Agents. Чтобы проверить, применилось ли изменение:

launchctl getenv NODE_EXTRA_CA_CERTS

Чтобы удалить позже:

launchctl unsetenv NODE_EXTRA_CA_CERTS

На macOS 10.10+ launchctl setenv сохраняется после перезагрузки для графических сессий. Если ваша организация использует MDM, ваш отдел ИТ может также развернуть это через LaunchAgent plist:

terminalbash

<!-- ~/Library/LaunchAgents/com.craft.proxy-ca.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.craft.proxy-ca</string>
  <key>ProgramArguments</key>
  <array>
    <string>/bin/launchctl</string>
    <string>setenv</string>
    <string>NODE_EXTRA_CA_CERTS</string>
    <string>/path/to/corporate-ca.pem</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
</dict>
</plist>

Windows

Однократный запуск из PowerShell:

$env:NODE_EXTRA_CA_CERTS = "C:\path\to\corporate-ca.pem"
& "$env:LOCALAPPDATA\craft-agents\AIKraft Agents.exe"

Постоянная настройка (все приложения, включая запуск из меню Пуск/на рабочем столе):

Вариант A — через интерфейс свойств системы:

1. Нажмите Win + R, введите sysdm.cpl, нажмите Enter
2. Перейдите на вкладку Дополнительно → нажмите Переменные среды
3. В разделе Переменные пользователя нажмите Создать
4. Имя переменной: NODE_EXTRA_CA_CERTS
5. Значение переменной: C:\path\to\corporate-ca.pem
6. Нажмите ОК во всех диалоговых окнах
7. Выйдите из системы и войдите снова (или перезагрузите), чтобы изменения вступили в силу

Вариант B — через PowerShell:

[System.Environment]::SetEnvironmentVariable(
  "NODE_EXTRA_CA_CERTS",
  "C:\path\to\corporate-ca.pem",
  "User"
)

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

Чтобы удалить позже, удалите переменную через свойства системы или выполните:

[System.Environment]::SetEnvironmentVariable("NODE_EXTRA_CA_CERTS", $null, "User")

Для развёртывания на уровне всей организации ИТ может установить это как переменную уровня Машина (через интерфейс свойств системы или групповая политика).

Linux

Однократный запуск из терминала:

NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem craft-agents

Постоянная настройка (все приложения, включая запуск с рабочего стола):

Добавьте в ~/.profile (читается логин-оболочками) и ~/.config/environment.d/proxy-ca.conf (читается сессиями systemd пользователя, которые используют большинство современных сред рабочего стола):

# ~/.config/environment.d/proxy-ca.conf
NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

Затем выйдите из системы и войдите снова. Чтобы проверить:

systemctl --user show-environment | grep NODE_EXTRA_CA_CERTS

На более старых средах рабочего стола, которые не используют сессии systemd пользователя, может потребоваться использовать ~/.pam_environment или ~/.xprofile вместо этого.

Получение сертификата ЦС

Ваш отдел ИТ должен предоставить сертификат ЦС корпоративного прокси. Если вам нужно извлечь его самостоятельно:

# Подключиться через прокси и захватить цепочку сертификатов
openssl s_client -connect api.anthropic.com:443 -proxy proxy.corp.com:8080 -showcerts /dev/null | openssl x509 -outform PEM > corporate-ca.pem

Сертификат должен быть в формате PEM (начинается с -----BEGIN CERTIFICATE-----). Если вы получили файл .cer или .der, преобразуйте его:

terminalbash

openssl x509 -inform DER -in corporate-ca.cer -out corporate-ca.pem

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

«Fetch failed» при входе через OAuth

Это обычно указывает на TLS-перехватывающий прокси. См. раздел TLS-перехватывающие прокси (корпоративные файрволы) выше.

Прокси работает для просмотра, но не для OAuth

Браузерная панель использует хранилище сертификатов Chromium (которое включает системные установленные сертификаты ЦС), тогда как обнаружение OAuth и обмен токенами используют fetch() Node.js (которая доверяет только встроенному пакету сертификатов Node). Установите NODE_EXTRA_CA_CERTS, чтобы мостить этот разрыв.

MCP-серверы не подключаются

Убедитесь, что имя хоста MCP-сервера не находится в списке «Без прокси» (если вы хотите прямой доступ). Для локальных MCP-серверов (транспорт stdio) настройки прокси не применяются — они работают как локальные подпроцессы.

Аутентификация прокси не работает

• Проверьте, что учётные данные работают с curl: curl -v --proxy http://user:pass@proxy:8080 https://api.anthropic.com
• URL-кодируйте специальные символы в пароле (например, p%40ss для p@ss)
• Некоторые корпоративные прокси используют аутентификацию NTLM, которая не поддерживается напрямую. Рассмотрите использование cntlm как локального моста NTLM-to-Basic.

Проверка активности прокси

Проверьте журнал приложения на наличие конфигурации прокси при запуске:

[proxy] Applying proxy settings: { enabled: true, hasHttpProxy: true, hasHttpsProxy: true, hasNoProxy: true }

Расположение журнала: ~/Library/Logs/@craft-agent/electron/main.log (macOS)