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	Порог автосжатия контекста (по умолчанию 350000); внедряется только при включённом автоконтексте
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".

Интеграция с системным окружением (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, который загружает этот файл автоматически.

Отключить можно параметром 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 удаляются перед пересылкой. Все остальные заголовки (включая anthropic-beta и anthropic-version) проходят без изменений.

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

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

Селектор /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>	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 в любой из форм, продолжает работать.

Правила грамматики алиасов: provider не может содержать / или -- и не может быть равен native; model не может содержать /. Маршруты, которые невозможно выразить читаемой формой, откатываются на хешированный алиас. Id моделей МОГУТ содержать -- (при разрешении деление происходит только по первому --); нативные слаги с -- откатываются на хешированную форму.

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

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

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

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

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

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

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

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

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

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

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

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

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)

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

• ocx-self закрепляет модель по умолчанию из селектора /model (с откатом на claudeCode.model); если нет ни того, ни другого, файл не создаётся. Наследование модели НЕ используется.
• В теле каждого агента есть директива <!-- ocx-route: <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 не затрагивается.

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

1. Через результат инструмента: вызовы Skill(...) со стороны ассистента — парное тело tool_result заменяется заглушкой, когда JSON-ввод в нижнем регистре содержит заблокированное имя.
2. Через текстовый блок: пользовательский текстовый блок длиной ≥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 журнала запросов.

Входящее преобразование (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	Отбрасывается
Function-инструменты	{type: "function"} (web_search* → {type: "web_search"})
tool_choice	auto→auto, none→none, any→required, именованный→{type:"function",name}
max_tokens	max_output_tokens
stop_sequences	stop

Случаи ошибок (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 с синтетической подписью
Кадры 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-*) используют директивы <!-- ocx-route: ... -->, а не аргумент model инструмента Agent. Убедитесь, что директива соответствует нужному маршруту. В качестве плейсхолдера модели передавайте "haiku".