Claude Code

opencodex обслуживает POST /v1/messages (а также count_tokens) наряду с /v1/responses, поэтому Claude Code может использовать все маршрутизируемые провайдеры — включая OAuth-входы, пулы аккаунтов, отказоустойчивое переключение (failover) ключей и сайдкары — без какой-либо дополнительной работы по аутентификации.

Быстрый старт

ocx claude

ocx claude убеждается, что прокси запущен, а затем запускает Claude Code с уже настроенным окружением:

Переменная	Значение
`ANTHROPIC_BASE_URL`	`http://127.0.0.1:<port>`
`ANTHROPIC_AUTH_TOKEN`	Только когда прокси требует API-ключ — иначе переменная НЕ устанавливается, поэтому ваш вход в claude.ai (подписка + коннекторы) остаётся активным
`CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY`	`1` (обнаружение моделей в нативном селекторе `/model`)
`CLAUDE_CODE_AUTO_COMPACT_WINDOW`	Порог автосжатия контекста (по умолчанию `829800`); внедряется только при включённом автоконтексте
`ANTHROPIC_MODEL`	`claudeCode.model` (необязательно)
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	`claudeCode.tierModels.haiku ?? claudeCode.smallFastModel` (необязательно; поддерживается и устаревшая `ANTHROPIC_SMALL_FAST_MODEL`)
`ANTHROPIC_DEFAULT_{OPUS,SONNET,FABLE}_MODEL`	`claudeCode.tierModels.*` (необязательно)
`CLAUDE_CODE_ALWAYS_ENABLE_EFFORT`	`1`, когда включён `alwaysEnableEffort` (условно)
`CLAUDE_CODE_MAX_CONTEXT_TOKENS` / `DISABLE_COMPACT`	Устаревшее переопределение контекста, когда задан `maxContextTokens` (условно)
Переменные, которые вы экспортируете сами, всегда имеют приоритет. Дополнительные аргументы передаются как есть: `ocx claude -p "hello"`.

Нативный запасной запуск, когда маршрутизация Claude выключена

Раньше ocx claude завершался с ошибкой, если маршрутизация Claude была выключена. Теперь вместо этого запускается нативный бинарник claude, поэтому команда остаётся полезной и с выключенной маршрутизацией:

Где выключена маршрутизация	Что происходит
`claudeCode.enabled: false` в конфигурации	Нативный запуск с уведомлением, что маршрутизация выключена
Запущенный прокси возвращает `enabled: false` из `GET /api/claude-code`	Нативный запуск и совет перезапустить службу после включения
`claudeCode.enabled` отсутствует или равен `true`	Маршрутизация через прокси, без изменений

Запасной запуск включает только явное false, поэтому прокси, не знающий об этом поле, остаётся маршрутизируемым. Отсутствие прокси тоже не является триггером — при включённой маршрутизации ocx claude по-прежнему запускает прокси.

Нативная сессия не должна наследовать состояние прокси, поэтому запасной запуск удаляет только те значения, принадлежность которых OpenCodex может доказать: ANTHROPIC_BASE_URL — лишь когда он указывает на собственный локальный адрес и настроенный порт этого прокси, а парный admission-токен выдан самим прокси; переключатели обнаружения и автоконтекста CLAUDE_CODE_*; и слоты моделей, которые разрешаются только через прокси (маршрутные псевдонимы и форма provider/model). Всё остальное — ваше и сохраняется: посторонний шлюз http://localhost:8080 и ваши собственные учётные данные sk-ant- остаются на месте.

Если сохранённый выбор в селекторе /model — модель только для прокси, нативная сессия перейдёт на claudeCode.model, когда та доступна нативно, а иначе предупредит передать --model <модель Anthropic>. Явный аргумент --model всегда имеет приоритет.

Интеграция с системным окружением (macOS)

Когда claudeCode.systemEnv установлен в true (по умолчанию: выключено), ocx start использует launchctl setenv, чтобы внедрить ANTHROPIC_BASE_URL и связанные переменные окружения Claude Code на уровне всей системы. Поэтому новые окна и вкладки терминала направляют обычные команды claude через прокси без обёртки ocx claude. Уже открытые оболочки не затрагиваются — их нужно открыть заново.

ocx stop и остановка прокси снимают внедрённые ключи (прежние значения не восстанавливаются — удаляются только ключи, внедрённые opencodex). Прокси также записывает ~/.opencodex/claude-env.sh; ocx start устанавливает source-хук в .zshrc только когда исполняемый Claude Code CLI найден в PATH. При запуске и выполнении ocx ensure хук, принадлежащий OpenCodex, удаляется, если файл Claude Code CLI не найден в PATH, не имеет права на выполнение или системная интеграция окружения выключена. Claude Desktop использует отдельный профиль и не вызывает установку shell-хука.

Отключить можно параметром claudeCode.systemEnv: false в конфигурации или переключателем в GUI. Функция доступна только на macOS; на других платформах используйте ocx claude.

Нативный проброс Claude (прямое подключение подписки)

Если переопределение аутентификации не задано, Claude Code сохраняет свой OAuth-вход в claude.ai и отправляет его прокси. Запросы к настоящим моделям claude*/anthropic*, на которые не претендует ни один алиас или запись карты моделей, пересылаются дословно на api.anthropic.com с вашими учётными данными — беты, подписи thinking, кеширование промптов и платёжная идентичность остаются полностью нативными, а маршрутизируемые модели продолжают работать в той же сессии через алиасы селектора.

Обработка заголовков: hop-by-hop-заголовки, а также host, content-length, accept-encoding, x-opencodex-api-key и origin всегда удаляются перед пересылкой. На non-loopback bind нативный passthrough также требует валидный proxy credential именно в x-opencodex-api-key; после этого Authorization и x-api-key принадлежат только Anthropic. Proxy admission secret в любом provider-заголовке удаляется, а настоящий provider credential в другом заголовке сохраняется. Неоднозначные credential-заголовки, объединённые запятыми, не пересылаются.

Проброс срабатывает, когда выполнены все условия: nativePassthrough не равен false; имя модели начинается с claude или anthropic; bearer-токен или x-api-key начинается с sk-ant-; разрешение алиасов и карты моделей возвращает ту же модель без изменений; а на non-loopback bind валиден dedicated proxy admission-header. Это также означает, что предупреждение «claude.ai connectors are disabled» с ocx claude больше не появляется.

Отключается параметром claudeCode.nativePassthrough: false; другой адрес задаётся через claudeCode.anthropicBaseUrl.

Claude Desktop через удалённый хаб

На подключённой машине ocx claude desktop apply или ocx claude desktop получает снимок Desktop с хаба и записывает его origin и точные выданные им ID моделей в локальную конфигурацию. Локальные псевдонимы заново не создаются. Режимы static/hybrid копируют список моделей; discovery-only использует origin хаба без встроенного списка.

Профиль, распределение по семействам и значения по умолчанию принадлежат хабу. Измените их на хабе, повторите применение на клиенте и заново выберите модель в Desktop. Это нужно и для старых псевдонимов, созданных только на клиенте. show, локальное редактирование и import/export остаются локальными операциями. При подключении ocx claude desktop import <path> --apply не поддерживается и отклоняется до сохранения; import без --apply остаётся локальным.

Снимок читается с учётными данными существующего подключения для доступа к данным, без администраторского токена и загрузки профиля на хаб. Старый несовместимый хаб, некорректный ответ или пустой список Desktop приводят к отказу применения, без подстановки локального каталога или loopback-адреса. Обновите или настройте хаб и повторите применение.

Это изменение псевдонимов не исправляет отдельный запрос #3719 о повторной передаче thinking / redacted_thinking и кеше промптов. Сам по себе доступ к прокси не включает нативный проброс Anthropic, но преобразованные маршруты Anthropic могут использовать кеш. Сохранение блоков при повторной передаче и сравнение попаданий в кеш остаются отдельной работой.

Ротация ключей, восстановление и отключение

Ротация и восстановление обновляют ключ в управляемом подключением профиле Desktop вместе с локальными учётными данными. Повторять apply вручную ради смены ключа не нужно. ID моделей, семейства, значения по умолчанию и текущий выбор профиля сохраняются; ротация не выбирает управляемый профиль заново и не включает отключённую интеграцию. В JSON CLI rotation: "committed" означает, что новый ключ активен, а rotation: "rolled_back" — что предыдущий сохранён или восстановлен, а не отозван. Неопределённое или неполное восстановление не выдаётся за успешную ротацию.

Первое применение при подключении сохраняет прежние управляемые настройки и выбор профиля. Повторное применение и ротация не заменяют эту исходную запись. ocx disconnect восстанавливает настройки подключения, сохраняя добавленные пользователем поля и другие профили. Прежний выбор возвращается только если управляемый профиль всё ещё выбран; более поздний выбор другого действительного профиля сохраняется. Созданный профиль с пользовательскими добавлениями остаётся читаемым в стандартном режиме. --keep-catalog сохраняет каталог, а не ключ подключения в Desktop.

Старый управляемый профиль без исходной записи можно мигрировать, если он однозначно относится к текущему хабу и распознанному ключу подключения. Это делают apply, ротация/восстановление или прямое отключение, без нового флага и предварительного apply. Предупреждение объясняет, что при отключении будет использован стандартный режим, поскольку прежние настройки не записаны. Удаляются только настройки шлюза, принадлежащие подключению; пользовательские поля и отдельный действительный выбор сохраняются. Это стандартный fallback, а не восстановление оригинала.

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

После применения, ротации/восстановления или возврата настроек полностью закройте и снова откройте Claude Desktop: работающий процесс может хранить прежний ключ. Автоматического перезапуска нет. Локальное отключение не отзывает ключ хаба и не стирает внешние копии; при необходимости отзовите ключ на хабе отдельно.

Селектор /model («From gateway»)

Claude Code 2.1.129+ обнаруживает модели шлюза через GET /v1/models?limit=1000 и показывает их в нативном селекторе /model в разделе «From gateway». Поскольку селектор принимает только id, начинающиеся с claude или anthropic, opencodex публикует маршрутизируемые модели как стабильные обратимые алиасы:

Интерфейс	Формат	Пример
Claude Code CLI	`claude-ocx-<provider>--<model>` (plain) или `claude-ocx2-…` (escaped)	`claude-ocx-native--gpt-5.6-sol`
Claude Desktop 3P	`claude-opus-4-8-<code>` (3-символьный base36-хеш)	`claude-opus-4-8-ncb`

Прокси выбирает семейство для каждого запроса: приоритет у ?ids=cli или ?ids=desktop; иначе user-agent claude-code/* получает читаемую CLI-форму, а остальные клиенты — Desktop-хеш. Оба семейства декодируются бессрочно — модель, сохранённая в settings.json в любой из форм, продолжает работать.

Если нижний селектор Claude Desktop не переключает модель в уже запущенном 3P-диалоге, можно попробовать /model <id>, но в затронутых сборках Desktop этот обходной способ тоже может не сработать. В issue #3782 сообщается, что в Windows с Claude Desktop 1.46388.4 диалог продолжает использовать исходную модель после изменений как через нижний селектор, так и через /model. Это сообщение не устанавливает, какой компонент клиента или маршрутизации вызывает такое поведение.

Можно также попробовать выбрать нужную модель по умолчанию в профиле Claude Desktop в OpenCodex, повторно применить профиль и начать новый диалог. Это шаг по устранению неполадки, а не гарантированное решение. OpenCodex не видит состояние селектора; он маршрутизирует id модели, переданный в каждом запросе. Проверьте, что отправляет клиент, в Logs → requestedModel.

Правила грамматики алиасов: provider не может содержать / или -- и не может быть равен native. Обычные id моделей (без / и ~) остаются с префиксом v1 claude-ocx-…. Id с / или ~ выпускаются с префиксом v2 claude-ocx2-… и экранированием (/ → ~s, ~ → ~t), например openrouter/anthropic/claude-opus-4-8 → claude-ocx2-openrouter--anthropic~sclaude-opus-4-8. Алиасы v1 декодируются литерально (исторические двухсимвольные последовательности ~s / ~t в id модели сохраняются); алиасы v2 раскрывают экранирование. Маршруты, которые невозможно выразить читаемой формой, откатываются на хешированный алиас. Id моделей МОГУТ содержать -- (при разрешении разбиение выполняется только по первому --); нативные слаги с -- откатываются на хешированную форму.

Порядок разрешения модели: удаление маркера [1m] → декодирование читаемого алиаса → декодирование Desktop-хеша → точное совпадение в modelMap → совпадение без даты (удаляется -20250514) → проброс.

Неразрешённый Desktop ID в формате даты может быть реальным нативным модельным ID, отсутствующим в результатах обнаружения. Если имеющихся данных недостаточно для разрешения ID, Messages и count-tokens возвращают HTTP 503 с фиксированной ошибкой desktop_model_mapping_unavailable; это не доказывает недействительность модели. Неизвестные старые хеш-псевдонимы по-прежнему дают HTTP 400. В обоих случаях дата не удаляется и другая маршрутизация не подставляется. Известные ID, зарегистрированные сопоставления и точные записи modelMap, включая распознанные реальные нативные ID, обрабатываются как прежде. Обновите обнаружение моделей или повторно примените профиль подключённого хаба перед новой попыткой; один лишь повтор не гарантирует разрешения.

Каждая запись содержит отображаемое имя вида gemini-3-pro (gemini) и полные возможности модели (шкала уровней рассуждений, типы thinking) в официальном формате ModelInfo. Настоящие модели Anthropic сохраняют канонические id в обоих интерфейсах.

Маркер контекстного варианта `[1m]`

Модели с подтверждённым контекстным окном 1M (или, при автоконтексте, больше 200k и не ниже порога сжатия) получают дополнительную строку …[1m] в селекторе. Её выбор заставляет Claude Code учитывать полный контекст 1M. Прокси удаляет суффикс [1m] (без учёта регистра) до разрешения алиасов и маршрутизации.

Автоконтекст (модели с большим контекстом без потолка 200k)

Для любой незнакомой модели Claude Code считает контекст равным 200k токенов. Автоконтекст (включён по умолчанию) исправляет это:

Модели, чьё реальное окно больше 200k и не меньше порога автосжатия, получают маркер [1m] в строках селектора и слотах окружения.
Внедряется CLAUDE_CODE_AUTO_COMPACT_WINDOW (по умолчанию 829800, диапазон 100000–1000000), чтобы в этой точке диалог автоматически резюмировался.

Три состояния конфигурации:

отсутствует / true: включено (по умолчанию)
false: выключено — ни маркеров, ни внедрения окна сжатия
задан устаревший maxContextTokens: автоконтекст неявно отключается

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

Нативные модели Anthropic с окном меньше 1M никогда не помечаются автоматически. Экспортированные вами значения всегда имеют приоритет (прокси использует ВАШЕ значение, чтобы решить, какие модели можно безопасно пометить). Некорректные значения, внесённые в конфигурацию вручную, откатываются к 829,800.

Эффективное окружение моделей

effectiveModelEnv вычисляет шесть слотов, внедряемых ocx claude, системным окружением и shell-файлом: ANTHROPIC_MODEL, четыре ANTHROPIC_DEFAULT_{OPUS,SONNET,HAIKU,FABLE}_MODEL и устаревший ANTHROPIC_SMALL_FAST_MODEL. Эффективное значение Haiku — tierModels.haiku ?? smallFastModel; оно подставляется в обе переменные Haiku.

Если отсутствуют и tierModels.haiku, и smallFastModel, OpenCodex оставляет обе переменные вспомогательной модели незаданными. Затем Claude Code выбирает нативную вспомогательную модель (сейчас Sonnet), что может привести к расходам у нативного провайдера.

Агенты из ростера (injectAgents)

Запуск/ensure прокси, ocx claude и сохранение связанных настроек в панели синхронизируют ваш ростер избранных подагентов (вкладка Subagents, до 5 моделей) плюс ocx-self в ~/.claude/agents/ocx-*.md.

ocx-self закрепляет модель по умолчанию из селектора /model (с откатом на claudeCode.model); если нет ни того, ни другого, файл не создаётся. Наследование модели НЕ используется.
В теле каждого агента есть директива  — по ней прокси закрепляет реальный маршрут. Поэтому аргумент model инструмента Agent не действует; передавайте "haiku" как плейсхолдер.
Frontmatter содержит алиас; маршрутизация определяется директивой.
Перезаписываются или удаляются только проверенные по маркеру файлы ocx-*.md, содержащие generated-by: opencodex; ваши собственные агенты никогда не затрагиваются.
Каждый файл синхронизируется атомарно (write + rename).
enabled: false или injectAgents: false удаляет все определения с подтверждённым владением.
PUT из GUI и изменения ростера пересинхронизируются немедленно; лаунчер и системное окружение синхронизируются при запуске.

Диспетчеризация: subagent_type: "ocx-gpt-5-6-sol". Цели с поддержкой 1M автоматически получают [1m].

Подмена встроенных скиллов (blockedSkills)

Встроенный в Claude Code скилл claude-api внедряет ~840 КБ (~136k токенов) документации Anthropic и автоматически срабатывает при упоминании моделей Claude. Маршрутизируемые модели на этом пакете не обучались, поэтому по умолчанию opencodex подменяет содержимое скилла короткой заглушкой в маршрутизируемых запросах. Нативный проброс Anthropic не затрагивается.

Обрабатываются два способа доставки:

Через результат инструмента: вызовы Skill(...) со стороны ассистента — парное тело tool_result заменяется заглушкой, когда JSON-ввод в нижнем регистре содержит заблокированное имя.
Через текстовый блок: пользовательский текстовый блок длиной ≥10 000 символов, начинающийся с Base directory for this skill: , — совпадение засчитывается, когда basename каталога равен заблокированному имени (без учёта регистра).

Настраивается через claudeCode.blockedSkills (по умолчанию ["claude-api"]; [] полностью отключает подмену). Заглушка сохраняет парность вызова инструмента и результата.

Карта моделей (перехват)

claudeCode.modelMap переписывает входящие id моделей Anthropic до маршрутизации:

{
  "claudeCode": {
    "modelMap": {
      "claude-sonnet-4-5": "gemini/gemini-3-pro",
      "claude-haiku-4-5": "gemini/gemini-3-flash"
    }
  }
}

Порядок поиска: алиас обнаружения → точный id → id без датировочного суффикса (-20250514) → проброс.

Матрица сайдкаров: веб-поиск и понимание изображений

Не у всех маршрутизируемых моделей одинаковый набор серверных (hosted) инструментов и поддержка изображений. opencodex закрывает эти пробелы до того, как ответит основная модель:

Сайдкар веб-поиска выполняет настоящий серверный поиск, а затем передаёт маршрутизируемой модели ответ и источники как результат инструмента.
Vision-сайдкар описывает вложенное изображение перед вызовом модели из списка noVisionModels, а затем заменяет изображение этим описанием.

Оба сайдкара могут использовать любой из двух бэкендов:

Бэкенд	Как работает	Что требуется
`openai`	Небольшая GPT-модель через провайдер ChatGPT `forward`	Вход в ChatGPT и включённый провайдер с `authMode: "forward"`
`anthropic`	Claude через сохранённый Anthropic OAuth; веб-поиск использует `web_search_20250305`, а vision отправляет изображение Claude для описания	Включённый провайдер с `adapter: "anthropic"`, `authMode: "oauth"`, чей активный сохранённый аккаунт не помечен `needsReauth`

Явно указанный backend всегда имеет приоритет. Если он не задан, opencodex выбирает anthropic, когда существует пригодный сохранённый аккаунт Anthropic OAuth; иначе — openai. Явный выбор anthropic без пригодных учётных данных завершается отказом (fail closed): opencodex не заимствует втихую учётные данные ChatGPT и не переключает бэкенды. Бэкенд OpenAI точно так же не включается без одновременного наличия входа в ChatGPT и forward-провайдера.

При внутреннем повторе маршрутизируемых запросов, пришедших из Claude, к запросу прикрепляется основной вход ChatGPT, поэтому OpenAI-сайдкары остаются доступными, даже если входящий bearer из Claude Code — это лишь учётные данные для доступа к прокси. Этот bearer никогда не пересылается основному маршрутизируемому провайдеру.

{
  "webSearchSidecar": {
    "backend": "anthropic",
    "model": "claude-sonnet-5",
    "maxSearchesPerTurn": 3
  },
  "visionSidecar": {
    "backend": "anthropic",
    "model": "claude-sonnet-5",
    "maxDescriptionsPerTurn": 8
  }
}

maxDescriptionsPerTurn ограничивает число новых описаний изображений за один ход основной модели. Попадания в кеш и дублирующиеся описания, уже находящиеся в обработке, лимит не расходуют. Успешные описания data:-изображений кешируются по бэкенду, модели, detail, байтам изображения и контексту запроса, поэтому одна и та же пара «изображение + контекст» не описывается заново при каждом повторе. Удалённые https:-изображения никогда не кешируются, потому что их содержимое может меняться.

Полный список ключей см. в справочнике по конфигурации. Веб-поиск и описание изображений через Anthropic OAuth повторяют уже принятый в репозитории подход к OAuth-отпечатку Claude Code, но, прежде чем полагаться на них в длительных автономных запусках, их стоит обкатать на вашем аккаунте и рабочей нагрузке.

Уровень рассуждений

Настройка /effort в Claude Code сохраняется при прохождении через адаптер:

Формат передачи	Сопоставление
`thinking.type: "adaptive"` + `output_config.effort`	Уровень передаётся напрямую (`minimal`\|`low`\|`medium`\|`high`\|`xhigh`\|`max`\|`ultra`)
`thinking.type: "enabled"` + `budget_tokens`	≤4096→`low`, ≤16384→`medium`, выше→`high`
`thinking.type: "disabled"`	Явно передаётся `reasoning: { effort: "none" }`, а `summary` опускается

Итоговое значение отображается в столбце Reasoning effort журнала запросов.

Входящее преобразование (Messages → Responses)

Прокси преобразует каждый запрос Anthropic Messages API в формат Codex Responses API:

Вход Messages	Выход Responses
`system` верхнего уровня	`instructions` (текстовые блоки объединяются через `\n\n`)
`messages[].role: "system"`	Также сворачивается в `instructions`
Текст / изображение пользователя	`input_text` / `input_image` (base64 → data URL)
Текст ассистента	`output_text`
`tool_use` ассистента	`function_call` (`input` → `arguments` в виде JSON-строки)
`tool_result` пользователя	`function_call_output` (`is_error` → префикс `[tool error]`)
Повтор `thinking` / `redacted_thinking`	Элементы `reasoning` с ограниченными конвертами `ocxr1` для подписей и скрытых данных
Function-инструменты	`{type: "function"}` (`web_search*` → `{type: "web_search"}`)
`tool_choice`	`auto`→`auto`, `none`→`none`, `any`→`required`, именованная функция→`{type:"function",name}`, размещённый WebSearch/web_search→`{type:"web_search"}`
`max_tokens`	`max_output_tokens`
`stop_sequences`	`stop`

На выбранном адаптере Anthropic сохраняются нескрытые подписанные блоки (включая пустой thinking) и непрозрачные блоки redacted. Политика hideThinkingSummary не меняется: локально скрытый подписанный текст не раскрывается клиентам Claude, а воспроизведение без потерь через эту границу пока не подтверждено. Старые объединённые конверты не восстанавливают порядок после отправки потокового текста. claudeCode.compatibility: "enforce" по-прежнему отклоняет thinking replay. Приём реальным Anthropic и улучшение кеша не доказаны; #3719 остаётся открытым.

Случаи ошибок (400): некорректный JSON; отсутствующий или пустой model; отсутствующий или пустой messages; неподдерживаемая роль; tool_result без tool_use_id; tool_use без id/name; именованный tool_choice без имени.

Исходящее преобразование (Responses → Messages SSE)

Событие Responses	Messages SSE
`response.created`	`message_start` + `ping`
Heartbeat	`ping`
Текстовые дельты	`content_block_start` → `content_block_delta` (text) → `content_block_stop`
Резюме/текст рассуждений	Блок `thinking` с повторно переданной подписью или ограниченным резервным конвертом `ocxr1`
Скрытое рассуждение	Блоки `redacted_thinking`, воспроизведённые из конверта рассуждений
Кадры function-call	Блок `tool_use` с `input_json_delta`
Завершающее событие	`message_delta` → `message_stop`
EOF до завершающего события	`api_error` в стиле 502

Сопоставление причин остановки: completed → tool_use (если был вызов инструмента) или end_turn; incomplete/max_output_tokens → max_tokens; incomplete/content_filter → refusal.

Таксономия ошибок: 400 invalid_request_error, 401 authentication_error, 402 billing_error, 403 permission_error, 404 not_found_error, 409 conflict_error, 413 request_too_large, 429 rate_limit_error, 504 timeout_error, 529 overloaded_error, прочие 5xx — api_error. Retry-After сохраняется.

Кеширование промптов и расход токенов

Запросы, маршрутизируемые в Anthropic: адаптер управляет точками кеширования для инструментов, системного содержимого и предпоследнего сообщения пользователя, а также автоматическим cache_control верхнего уровня. На стабильных ходах диалога попадание в кеш обычно составляет около 99,9%.

Нативная маршрутизация OpenAI/ChatGPT: формируется сессионный prompt_cache_key (из metadata.user_id, если он есть, иначе — из хеша системного содержимого) и заголовок session_id для привязки к кешу. В ключ кеша входят модель и полные схемы инструментов.

Арифметика токенов: в ответе Anthropic из input_tokens вычитаются cached_tokens и cache_write_tokens, которые выводятся как cache_read_input_tokens и cache_creation_input_tokens. Журнал запросов сводит их обратно в инклюзивный inputTokens: чтения попадают и в cachedInputTokens, и в cacheReadInputTokens, записи — в cacheCreationInputTokens. Страница Usage показывает попадания в кеш и создание кеша по отдельности.

count_tokens: для маршрутизируемых моделей используется приближённая оценка (сериализованные system + messages + tools). Для нативных моделей Anthropic с учётными данными sk-ant- запрос пробрасывается на настоящую конечную точку Anthropic /v1/messages/count_tokens.

Отладочный захват

Захват входящих запросов управляется командой ocx debug claude on|off|status|reset, переменной OCX_CLAUDE_DEBUG=1 или запросом PUT /api/debug {"claude": true}. GET /api/claude/inbound-debug возвращает {enabled, entries} (сначала новые, кольцевой буфер на 20 записей).

Каждая запись фиксирует: at, endpoint, model, resolvedModel, stream, maxTokens, thinkingType, thinkingBudgetTokens, outputConfigEffort, metadataKeys, hasMetadataUserId, hasSystem, исходный anthropicBeta и восьмисимвольные HMAC-теги равенства для id пользователя и system. Текст промпта, сырой объект и стабильный межзапусковый хеш не сохраняются. Отключение отладки Claude немедленно очищает кольцевой буфер.

GUI (страница Claude)

В боковой панели дашборда есть отдельная страница Claude (под API) и переключатель Claude ON (надпись намеренно одинакова на всех языках). Страница показывает:

Аварийный выключатель входящего трафика (переключатель enabled)
Быстрый старт (ocx claude) и блок ручной настройки окружения
Селектор Fast Mode (Auto / ON / OFF)
Переключатель автоконтекста и выпадающий список порога сжатия
Переключатель автоматической регистрации подагентов
Редактор перехвата моделей (modelMap)
Живой предпросмотр алиасов селектора

GET /api/claude-code возвращает эффективные значения по умолчанию, конфигурацию, реестр контекстных окон, эффективное окружение, доступные id маршрутов, алиасы и порт. PUT /api/claude-code — частичное обновление, пропущенные поля сохраняются; null сбрасывает значения context/blocklist/compact-window.

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

Claude Code пишет «Did 0 searches» — текущие сборки преобразуют завершённые элементы Responses web_search_call в парные блоки Anthropic server_tool_use и web_search_tool_result, включая usage.server_tool_use.web_search_requests. Если в старой сборке поиск выполнялся, но Claude Code всё равно насчитывал ноль, обновите opencodex.

Сайдкар не активируется — для backend: "openai" проверьте, что выполнен вход в ChatGPT и есть включённый провайдер с authMode: "forward". Для backend: "anthropic" проверьте, что активный сохранённый аккаунт Anthropic OAuth не помечен needsReauth. Явный выбор Anthropic без таких учётных данных намеренно завершается отказом.

«claude.ai connectors are disabled» — в вашей оболочке задан ANTHROPIC_API_KEY или ANTHROPIC_AUTH_TOKEN. ocx claude намеренно НЕ устанавливает ANTHROPIC_API_KEY; если вы экспортировали его сами, снимите переменную. ocx claude внедряет ANTHROPIC_BASE_URL, обнаружение моделей, автоконтекст и настроенные слоты моделей — но никогда ANTHROPIC_API_KEY.

Модели не появляются в селекторе /model — убедитесь, что установлена CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 (с ocx claude — автоматически). Запустите ocx claude, чтобы обновить кеш моделей шлюза в ~/.claude/cache/gateway-models.json. Проверьте, что claudeCode.enabled не равен false.

Устаревшее окружение после смены порта — если порт прокси изменился, в старых оболочках может остаться устаревший ANTHROPIC_BASE_URL. Откройте новый терминал или повторно запустите ocx claude.

Потолок контекста 200k, хотя модель больше — выберите в селекторе вариант [1m] или включите автоконтекст (включён по умолчанию). Если строки [1m] в селекторе нет, подтверждённое контекстное окно модели может быть меньше порога автосжатия.

Большой расход токенов при загрузке скиллов — встроенный скилл claude-api (~136k токенов) автоматически загружается при упоминании моделей Claude. Для нативного проброса это нормально; для маршрутизируемых моделей opencodex по умолчанию подставляет заглушку (blockedSkills: ["claude-api"]).

Подагент отправляется не в ту модель — агенты из ростера (ocx-*) используют директивы , а не аргумент model инструмента Agent. Убедитесь, что директива соответствует нужному маршруту. В качестве плейсхолдера модели передавайте "haiku".