Как подключить модели OpenRouter в Codex Desktop

Codex Desktop позволяет работать не только с моделями OpenAI, но и подключать другие модели через совместимые API. Один из способов сделать это – использовать OpenRouter, где доступны модели разных разработчиков

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

Разберём, как подключить OpenRouter к Codex Desktop на macOS, проверить основные возможности выбранной модели и сохранить обнаруженные ограничения для дальнейшей работы

Выбор модели и API-ключа

Для начала понадобится аккаунт OpenRouter и API-ключ, который можно создать в настройках сервиса. Саму модель выберите в каталоге OpenRouter

В каталоге у каждой модели есть API ID. Именно его нужно будет указать в настройках Codex. Если хотите использовать агента для работы с кодом, выбирайте модель с поддержкой вызовов инструментов (tools⁠)

После подключения проверим, может ли выбранная модель читать и изменять файлы, запускать команды и продолжать работу с полученными результатами

Для обмена запросами используется Responses API OpenRouter. Через него Codex отправляет сообщения модели и получает ответы, включая вызовы инструментов

Сохранение API-ключа

Codex Desktop и Codex CLI используют общий конфигурационный файл, но есть отличие в способе получения переменных окружения

Приложение, запущенное через интерфейс macOS, не обязательно наследует переменные из ~/.zshrc или другого файла конфигурации оболочки. Поэтому обычный export OPENROUTER_API_KEY в терминале может работать для CLI, но оказаться недоступным в Desktop

Чтобы не зависеть от переменных окружения, сохраним ключ в отдельном файле и настроим Codex на его чтение

Создайте ~/.codex/openrouter-api-key и откройте его в редакторе

umask 077
mkdir -p ~/.codex
touch ~/.codex/openrouter-api-key
chmod 600 ~/.codex/openrouter-api-key
nano ~/.codex/openrouter-api-key

Вставьте API-ключ одной строкой без кавычек и названия переменной. Для сохранения в nano нажмите Ctrl+O⁠, подтвердите имя файла клавишей Enter и закройте редактор через Ctrl+X

Проверим права доступа и узнаем абсолютный путь к файлу

ls -l ~/.codex/openrouter-api-key
printf '%s\n' "$HOME/.codex/openrouter-api-key"

Права должны начинаться с -rw-------⁠. Это означает, что читать и изменять файл может только его владелец

Вторая команда выведет путь, который понадобится при настройке провайдера. Сам ключ обе команды не показывают

Дальше Codex будет запускать /bin/cat⁠, передавая ему путь к файлу. Команда прочитает ключ и вернёт его приложению для авторизации. Поэтому в конфигурации потребуется абсолютный путь, а не сокращение через ~ или $HOME

Подключение OpenRouter к Codex

Настройки провайдеров хранятся в ~/.codex/config.toml⁠. Этот файл используется и настольным приложением, и Codex CLI. Конфигурация провайдера должна находиться именно здесь, поскольку проектный .codex/config.toml не может переопределять model_provider и model_providers

Полностью закройте Codex Desktop перед редактированием файла

Если конфигурация уже существует, сначала создайте резервную копию

config_backup=$(mktemp "$HOME/.codex/config.toml.backup.XXXXXX") &&
  cp -p "$HOME/.codex/config.toml" "$config_backup" &&
  printf 'Копия конфига: %s\n' "$config_backup"

Команда сохранит действующие настройки и выведет путь к копии. Если config.toml ещё нет, этот шаг пропустите

Теперь откройте файл

nano ~/.codex/config.toml

Добавьте определение провайдера OpenRouter

model = "PROVIDER/MODEL_ID"
model_provider = "openrouter"
web_search = "disabled"

[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
wire_api = "responses"
supports_websockets = false

[model_providers.openrouter.auth]
command = "/bin/cat"
args = ["/Users/YOUR_NAME/.codex/openrouter-api-key"]

Вместо PROVIDER/MODEL_ID укажите API ID выбранной модели из каталога OpenRouter. В args подставьте абсолютный путь к файлу с ключом, полученный ранее

Параметры model⁠, model_provider и web_search должны находиться в начале TOML-файла, до первого объявления таблицы в квадратных скобках. Если они уже существуют, измените текущие значения, а не добавляйте повторно

То же относится к [model_providers.openrouter]⁠. Повторное объявление одной таблицы или ключа приведёт к ошибке разбора конфигурации

Здесь base_url указывает адрес API OpenRouter, а wire_api = "responses" задаёт протокол обмена запросами. Параметр supports_websockets = false отключает использование WebSocket-транспорта, который для этого подключения не требуется. Такие настройки приведены в документации OpenRouter для Codex Desktop

Отдельного внимания заслуживает таблица [model_providers.openrouter.auth]

Codex поддерживает получение ключа через переменную окружения env_key⁠, но при таком способе подключения каталог моделей OpenRouter может не загружаться. Из-за этого сторонние модели иногда определяются как неизвестные и получают резервные значения метаданных

Командная авторизация через auth позволяет Codex получать ключ отдельно и загружать каталог провайдера. В нашем случае команда /bin/cat читает ключ из локального файла, поэтому переменная окружения не нужна

Не объединяйте этот вариант авторизации с env_key⁠, experimental_bearer_token или requires_openai_auth⁠. Если такие параметры уже есть в определении OpenRouter, удалите их. Ограничение описано в документации конфигурации Codex

Параметр web_search = "disabled" временно отключает встроенный веб-поиск, чтобы на первом этапе проверять работу модели без дополнительных сетевых инструментов

Если в конфигурации остались вручную заданные model_context_window⁠, model_reasoning_effort или model_verbosity от другой модели, на время первоначальной проверки лучше убрать эти переопределения. Иначе Codex может использовать неподходящие для новой модели значения

Сохраните конфигурацию и заново запустите Codex Desktop

Проверка работы с файлами

Начните с нового локального чата в тестовом проекте. Для первой проверки достаточно попросить модель ответить одним словом

Если ответ получен, откройте Activity в OpenRouter и найдите запрос по времени. Сверьте фактически использованную модель с API ID, указанным в конфигурации

Это позволит убедиться, что запрос действительно прошёл через OpenRouter, а не через прежнего провайдера

Теперь проверим, может ли модель выполнять действия с файлами. Выберите тестовую директорию, в которой нет файла openrouter-check.txt⁠, и отправьте агенту запрос

Создай в текущей папке файл openrouter-check.txt с одной строкой connection-ok. Прочитай созданный файл и покажи его содержимое

После выполнения откройте файл самостоятельно и проверьте, что в нём действительно находится connection-ok

Затем попросите агента изменить тот же файл

Добавь в openrouter-check.txt вторую строку update-ok, сохранив первую. Прочитай файл и покажи обе строки

В результате файл должен содержать

connection-ok
update-ok

Эти два задания позволяют проверить базовые операции создания, чтения и изменения файлов

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

Если все действия прошли успешно, можно удалить тестовый файл и переходить к остальным инструментам

Проверка инструментов Codex

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

Проблемы иногда возникают именно при их вызове. Модель может неправильно сформировать аргументы, не обработать результат или попытаться использовать инструмент, тип которого не поддерживается текущим сочетанием модели и провайдера

Поэтому полезно провести отдельную проверку доступных инструментов, прежде чем поручать агенту изменения в рабочем проекте

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

Для этого можно использовать следующий запрос

Проверь совместимость текущей модели и провайдера с инструментами, доступными тебе в этой сессии Codex

1. Определи доступные инструменты по их схемам и запиши точные имена. Если есть механизм поиска отложенных инструментов, используй его. Не добавляй инструменты, которых не удалось обнаружить

2. Для каждого найденного инструмента выбери минимальное безопасное действие, соответствующее его назначению. Выполняй проверки по одной, чтобы можно было связать результат с конкретным вызовом

3. Для проверки файловых операций создай отдельный новый временный каталог. Проверь создание, чтение, поиск и изменение тестовых файлов. Существующие файлы проекта не меняй

4. Если доступен запуск команд, выполни безопасную команду без изменения системы. Если для продолжения запущенного процесса предусмотрен отдельный инструмент, проверь и его

5. Остальные инструменты проверяй только операциями чтения или специально подготовленными тестовыми данными. Не отправляй сообщения, не изменяй внешние сервисы, не устанавливай программы и не запускай платные операции. Если инструмент нельзя проверить безопасно или без дополнительных разрешений, отметь его как непроверенный

6. Для каждого теста дождись результата выполнения. Успешная отправка вызова ещё не означает, что инструмент сработал

7. Разделяй ошибки несовместимости, разрешений, неверных аргументов, сети и внешнего сервиса. Если аргументы не соответствуют схеме, исправь их и повтори проверку. Общую ошибку без подробностей не считай доказательством несовместимости

8. Если среда явно сообщает, что инструмент или его тип не поддерживается, сохрани точное имя и текст ошибки. Не повторяй тот же заведомо неподдерживаемый вызов

9. Если один инструмент не работает, продолжи остальные независимые проверки, пока сессия остаётся работоспособной

10. Подготовь таблицу с именем инструмента, тестовым действием, результатом и текстом ошибки. Используй статусы «работает», «не поддерживается», «ошибка» и «не проверен»

Отдельно перечисли инструменты, которые не удалось обнаружить или проверить. Не утверждай, что проверил все инструменты Codex вообще. Выводы должны относиться только к доступной сессии и фактически выполненным действиям

AGENTS.md во время проверки не изменяй

Главная задача такой проверки – определить не просто наличие инструмента, а возможность получить от него корректный результат через выбранную модель

Если модель успешно вызвала инструмент чтения файла, это ещё не доказывает, что она умеет изменять файлы. А успешная генерация аргументов не подтверждает, что инструмент выполнился

Ошибки тоже необходимо интерпретировать правильно. Например, отказ из-за недостаточных разрешений не означает, что модель несовместима с инструментом. То же касается недоступности внешнего сервиса или ошибки, вызванной неверными аргументами

Если вызов инструмента оборвал ответ целиком, передайте сообщение об ошибке в следующем запросе и попросите продолжить остальные независимые проверки. Повторять заведомо неподдерживаемую операцию нет смысла

Ограничения модели в AGENTS.md

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

Чтобы избежать повторных ошибок, подтверждённые ограничения можно записать в AGENTS.md⁠. Тогда агент будет учитывать их при работе с проектом

Поручите ему подготовить соответствующий раздел на основе полученных результатов

По результатам проверки инструментов добавь в AGENTS.md раздел «Совместимость инструментов»

Сохрани все существующие инструкции

Укажи текущую модель, провайдера и версию Codex, если эти сведения достоверно известны. Не угадывай отсутствующие значения

Для каждого подтверждённо неподдерживаемого инструмента запиши точное имя, текст ошибки и проверенную альтернативу, если она существует

Не включай в список несовместимых инструментов ошибки разрешений, аргументов, сети или внешних сервисов

Добавь правило, запрещающее вызывать подтверждённо неподдерживаемые инструменты с указанной моделью и провайдером. Если есть проверенная замена с подходящими правами доступа и результатом, разреши использовать её. Если замены нет, требуй сообщать о невозможности действия

Запрети имитировать результаты инструментов и обходить ограничения доступа

Укажи, что после смены модели, провайдера или версии Codex совместимость необходимо проверить повторно

Если неподдерживаемые инструменты не обнаружены, не создавай список запретов. Если AGENTS.md нельзя изменить, выведи готовый фрагмент для ручного добавления

В инструкции стоит сохранять только ограничения, подтверждённые конкретными вызовами. Если инструмент просто не появился в списке текущей сессии, это ещё не доказывает его несовместимость с моделью

Не следует и переносить результаты проверки на другие модели. Даже внутри одного провайдера поведение может отличаться, поэтому после смены API ID список ограничений нужно пересмотреть

Диагностика ошибок подключения

Если Codex не запускается с новой конфигурацией или модель не отвечает, сначала нужно определить, на каком этапе произошла ошибка. Проблемы с API-ключом, определением модели и выполнением инструментов требуют разных решений

Ошибки авторизации

При ответе 401 проверьте путь к ключу в auth.args⁠, права файла и сам ключ в OpenRouter

Файл должен содержать одну строку с действующим ключом. Если путь указан неправильно или команда /bin/cat не может прочитать файл, Codex не получит данные для авторизации

Сообщение Missing environment variable может означать, что в конфигурации провайдера остался параметр env_key⁠. В нашем варианте ключ передаётся через команду auth⁠, поэтому env_key необходимо удалить

Ошибки определения модели

Если OpenRouter возвращает model not found⁠, проверьте API ID. Он должен точно соответствовать идентификатору в каталоге, включая название провайдера перед косой чертой

Отдельная ситуация – предупреждение Codex об неизвестной модели или использовании fallback metadata

Оно может возникать, когда Codex не получает сведения о модели из каталога провайдера и использует резервные метаданные

В этом случае проверьте, что применяется именно командная авторизация [model_providers.openrouter.auth]⁠, а не env_key

Также посмотрите, не задан ли в конфигурации model_catalog_json⁠. Этот параметр позволяет использовать локальный каталог моделей, который может иметь приоритет над загружаемыми данными. Если он был добавлен для другого провайдера, временно уберите переопределение и проверьте загрузку модели снова. Параметр описан в справочнике конфигурации Codex

Ошибки OpenRouter

Если запрос дошёл до OpenRouter, но сервис отказался его выполнять, ориентируйтесь прежде всего на HTTP-код и сообщение об ошибке

Код	Что проверить
402	Доступный баланс аккаунта или ключа. Если передан Retry-After⁠, возможен временный лимит бюджета одновременно выполняемых запросов
403	Права доступа, ограничения ключа или организации, фильтры и запреты на обработку запроса
429	Превышение лимита запросов и наличие заголовка Retry-After

Подробнее эти ответы разобраны в документации ошибок OpenRouter

Если Codex сообщает Server tool request failed⁠, найдите конкретный вызов, после которого возникла ошибка. Без этой информации нельзя определить, связана ли проблема с моделью, форматом аргументов или выполнением инструмента

После любой ошибки, прервавшей работу агента, сначала проверьте состояние проекта. Инструмент мог успеть изменить файлы или выполнить часть команд до сбоя. Повторный запуск всей задачи без проверки способен привести к дублированию изменений

Возврат к прежней модели

Если выбранная модель не подходит для работы или возникают проблемы с совместимостью, восстановите предыдущую конфигурацию Codex

Полностью закройте приложение и верните ~/.codex/config.toml из резервной копии

Если после её создания в конфигурации появились другие нужные изменения, не заменяйте файл целиком. Восстановите прежние значения модели и провайдера вручную, удалив добавленные настройки OpenRouter

Если файла до подключения не существовало, удалите только параметры, созданные для этого провайдера

После сохранения запустите Codex Desktop и откройте новый чат, чтобы проверить работу прежней модели

Если OpenRouter больше не используется, отзовите API-ключ в настройках сервиса и удалите локальный файл ~/.codex/openrouter-api-key

Само подключение сторонней модели к Codex занимает немного времени. Основные сложности обычно появляются позже, когда агент начинает выполнять действия с файлами, запускать команды и использовать другие инструменты

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