Як налаштувати Codex config.toml: власний API, проксі та поширені помилки

Codex зберігає налаштування в одному файлі — config.toml: яку модель використовувати, до якого API звертатися та скільки агент може робити без запиту дозволу. Формат кілька разів змінювався у 2026 році, і в багатьох посібниках, опублікованих на початку року, наведено налаштування, через які Codex тепер не запускається.

У цьому посібнику спочатку наведено робочий конфігураційний файл, а потім — налаштування, які змінюють найчастіше: профілі, параметри проєкту, ізольоване середовище та проксі. Наприкінці — перелік помилок, які можуть з’явитися, і пояснення, що означає кожна з них. Перевірено за документацією OpenAI та протестовано на Codex CLI 0.162.1 19 жовтня 2026 року. У прикладах використовується AIHubMix; так само працюватиме будь-який шлюз із підтримкою OpenAI Responses API.

Коротко

• Файл розташований за адресою ~/.codex/config.toml, а у Windows — C:\Users\<you>\.codex\config.toml.
• Для власного провайдера потрібні base_url, wire_api = "responses" і env_key. Ключ API зберігається в змінній середовища.
• Профілі тепер зберігаються в окремих файлах ~/.codex/<name>.config.toml, які вибираються за допомогою --profile <name>.
• Файл репозиторію .codex/config.toml працює лише в довірених проєктах і не може змінювати провайдера.
• Після кожної зміни перезапускайте Codex: файл читається лише під час запуску.

Де зберігається config.toml

Основні налаштування містяться у файлі ~/.codex/config.toml. Його читають і CLI, і розширення для IDE. Якщо файлу ще немає, створіть його.

Налаштування також можна додати з двох інших місць:

• Файли профілів — ~/.codex/<name>.config.toml, які використовуються, лише якщо запустити Codex із параметром --profile <name>.
• Файли проєкту — .codex/config.toml у репозиторії, де зберігаються налаштування для спільного використання командою.

Якщо запустити Codex у WSL2 на Windows, він читатиме домашню директорію Linux (/home/<you>/.codex/config.toml), а не директорію Windows. Якщо встановлено CODEX_HOME, Codex використовуватиме цю папку замість ~/.codex.

Мінімальна робоча конфігурація

Цей повний файл ~/.codex/config.toml спрямовує запити Codex до AIHubMix:

model = "gpt-6-sol"
model_provider = "aihubmix"
model_reasoning_effort = "high"

[model_providers.aihubmix]
name = "AIHubMix"
base_url = "https://aihubmix.com/v1"
wire_api = "responses"
env_key = "AIHUBMIX_API_KEY"

• model — ідентифікатор моделі, до якої надсилатимуться запити, а model_reasoning_effort — рівень міркувань за замовчуванням.
• model_provider має збігатися з назвою в [model_providers.<name>]. Не використовуйте openai, ollama чи lmstudio: ці назви зарезервовано для вбудованих провайдерів Codex.
• base_url — адреса API провайдера. Тепер Codex приймає лише значення wire_api = "responses".
• env_key — це назва змінної середовища, а не сам ключ.

Потім задайте значення цієї змінної, використавши ключ із консолі AIHubMix:

# macOS / Linux: add this line to ~/.zshrc or ~/.bashrc, then open a new terminal
export AIHUBMIX_API_KEY=sk-...

# Windows PowerShell: takes effect in new terminals
setx AIHUBMIX_API_KEY "sk-..."

Відкрийте новий термінал, запустіть codex і поставте будь-яке запитання. Якщо Codex відповість, провайдер працює. Авторизація в Codex тут ні до чого: ключ із codex login ніколи не надсилається власному провайдеру.

Профілі: окремий файл для кожного налаштування

Профіль містить лише параметри, що відрізняються від основної конфігурації, наприклад глибше міркування та режим лише для читання під час перевірки коду. Кожен профіль зберігається в окремому файлі поруч із config.toml, а ключі в ньому вказуються на верхньому рівні:

# ~/.codex/review.config.toml
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"

codex --profile review

Це змінилося у Codex 0.134.0. У старіших посібниках профілі задавалися безпосередньо у файлі config.toml у вигляді таблиць [profiles.review], а вибрати профіль можна було за допомогою profile = "review". Тепер Codex відмовляється запускатися, якщо задано цей параметр вибору. Якщо окремо залишити таблицю [profiles.review], її буде проігноровано без жодного повідомлення, тож її налаштування непомітно перестануть працювати. Щоб перейти на новий формат, перенесіть ключі кожної таблиці до файлу ~/.codex/<name>.config.toml, а потім видаліть таблицю та рядок profile = .... Докладніше див. у посібнику OpenAI з розширеного налаштування.

Конфігурація проєкту: .codex/config.toml

Файл .codex/config.toml у репозиторії дає змогу команді спільно використовувати модель за замовчуванням, рівень міркувань або режим ізольованого середовища. Codex читає його лише в проєктах, позначених як довірені у вашому власному файлі ~/.codex/config.toml:

[projects."/Users/you/code/my-app"]
trust_level = "trusted"

Файл проєкту не може змінити адресу надсилання запитів. Codex ігнорує в ньому ключі model_provider, model_providers, openai_base_url, profile, notify та деякі інші й виводить попередження. Зберігайте налаштування провайдера у файлі ~/.codex/config.toml. У проєкті все одно можна вибрати модель, але запити надсилатимуться до вашого провайдера.

Яке налаштування має пріоритет

Якщо той самий ключ задано в кількох місцях, у розділі Основи конфігурації документації OpenAI вказано такий порядок пріоритету — від найвищого:

1. Прапорці командного рядка, зокрема перевизначення за допомогою -c
2. Файл проєкту .codex/config.toml
3. Профіль, вибраний за допомогою --profile
4. Ваш файл ~/.codex/config.toml
5. Системний файл конфігурації /etc/codex/config.toml
6. Вбудовані налаштування Codex за замовчуванням

Зверніть увагу: файл проєкту має вищий пріоритет, ніж профіль. Якщо налаштування профілю, здається, не діє, перевірте, чи вказано той самий ключ у файлі .codex/config.toml репозиторію.

Щоб змінити налаштування лише для одного запуску, використовуйте -c:

codex -c model_reasoning_effort=high

Ізольоване середовище та підтвердження

Два ключі визначають, що Codex може робити самостійно. sandbox_mode задає, до чого можуть звертатися його команди, а approval_policy — коли він зупиняється, щоб запитати дозвіл.

sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = true   # off by default

Ці два параметри незалежні: never вимикає запити дозволу, але не послаблює обмеження ізольованого середовища. У режимі workspace-write команди не можуть отримувати доступ до мережі, доки не встановлено network_access = true.

Робота через проксі

У Codex немає налаштування проксі у файлі config.toml. Він використовує стандартні змінні середовища:

export HTTPS_PROXY=http://127.0.0.1:7890   # your proxy address
export NO_PROXY=localhost,127.0.0.1

У документації OpenAI ці змінні не згадуються, тому їхню роботу перевірили на Codex 0.162.1: усі запити, зокрема до власного провайдера, проходили через HTTPS_PROXY (або ALL_PROXY), а до хостів зі списку NO_PROXY зверталися напряму. Файли PAC не підтримуються, тож укажіть безпосередньо адресу проксі. Якщо корпоративний проксі використовує власний кореневий сертифікат, задайте в CODEX_CA_CERTIFICATE шлях до нього, як описано в довіднику змінних середовища.

Більше моделей у /model

У списку моделей /model відображаються лише моделі OpenAI. Щоб вибирати з нього моделі GLM, Claude, Gemini або DeepSeek, додайте каталог моделей: JSON-файл, указаний ключем верхнього рівня model_catalog_json. Розмістіть цей ключ перед першим рядком [table], інакше TOML вважатиме його частиною цієї таблиці, а Codex його проігнорує.

Каталог замінює вбудований список, і кожному запису потрібен довгий перелік полів, тож найкраще згенерувати його, а не створювати вручну. У посібнику AIHubMix з Codex CLI є скрипт, який створює каталог із 30 найпопулярніших моделей AIHubMix. Настільний застосунок може й далі приховувати власні моделі у списку вибору (openai/codex#19694), тож змінюйте модель у терміналі.

Поширені помилки та їх значення

Нижче наведено повідомлення, які Codex 0.162.1 виводив для кожної з цих помилок.

legacy profile = "..." config is no longer supported
У вашому config.toml досі є застарілий рядок profile = "...". Перенесіть профіль до окремого файлу, як описано вище. Якщо запустити --profile x, коли існує стара таблиця [profiles.x], з’явиться схожа помилка: --profile x cannot be used while ... contains legacy ... config.

wire_api = "chat" is no longer supported
Codex більше не підтримує API Chat Completions. Змініть значення на wire_api = "responses". Провайдер, що підтримує лише Chat Completions, не працюватиме без проксі-перекладача.

model_providers contains reserved built-in provider IDs
Ви назвали провайдера openai, ollama або lmstudio. Змініть назву таблиці та значення model_provider на інші.

approval_policy = "untrusted" is no longer supported
Видаліть цей рядок або використайте on-request.

Missing environment variable: AIHUBMIX_API_KEY
Змінну, названу в env_key, не задано в терміналі, з якого запущено Codex. Відкрийте новий термінал або виконайте source ~/.zshrc і знову запустіть Codex.

401 Unauthorized після кількох рядків «Reconnecting...»
Запит було надіслано без ключа. Перевірте, чи задано env_key у таблиці провайдера. Дані входу, збережені у auth.json, для власних провайдерів не використовуються.

Model metadata for ... not found. Defaulting to fallback metadata
У Codex немає вбудованих налаштувань для цієї моделі, що цілком нормально для моделей не від OpenAI. Запити все одно працюватимуть. Додайте каталог моделей, якщо потрібні відповідні налаштування та відображення моделі в /model.

Ignored unsupported project-local config keys
У файлі репозиторію .codex/config.toml задано ключ, який працює лише у вашому власному конфігураційному файлі, зазвичай це model_provider. Перенесіть його до ~/.codex/config.toml.

missing field base_instructions
У записі каталогу моделей бракує обов’язкового поля, тому Codex відхиляє весь файл. Згенеруйте каталог скриптом, а не редагуйте його вручну.

Якщо налаштування не застосовується

• Перезапустіть Codex після редагування.
• Переконайтеся, що ключі верхнього рівня стоять перед першим рядком [table].
• Перевірте файл .codex/config.toml репозиторію: він має пріоритет над профілем.
• Перевірте, чи не залишилася таблиця [profiles.x].
• Запустіть codex doctor: ця команда перевіряє встановлення, конфігурацію та авторизацію.

Щоб використовувати в Codex моделі OpenAI, Anthropic, Google, Zhipu, DeepSeek та інших провайдерів за допомогою одного ключа, скористайтеся AIHubMix: він надає до них доступ через Responses API за адресою https://aihubmix.com/v1. Почніть із наведеної вище мінімальної конфігурації та додайте каталог моделей, якщо захочете перемикатися між моделями через /model.

Поширені запитання

Де розташований файл конфігурації Codex config.toml?
У macOS і Linux — у ~/.codex/config.toml, а у Windows — у C:\Users<you>.codex\config.toml. Якщо задано CODEX_HOME, файл зберігається в цій папці.

Чи потрібно перезапускати Codex після зміни config.toml?
Так. Codex читає файл під час запуску, тож закрийте й знову відкрийте сеанс термінала або програму.

Чому Codex повідомляє «конфігурація застарілого профілю більше не підтримується»?
У Codex 0.134.0 прибрали профілі, визначені в config.toml. Перенесіть кожен профіль у ~/.codex/name.config.toml, видаліть старі рядки й запустіть Codex із параметром --profile name.

Чи можна й далі використовувати wire_api = "chat"?
Ні. Codex приймає лише wire_api = "responses". Для провайдера, який підтримує лише Chat Completions, потрібен проксі, що перетворює запити на формат Responses API.

Чому мій власний провайдер повертає 401, хоча я ввійшов у Codex?
Ключ входу з auth.json не надсилається власним провайдерам. Додайте env_key до таблиці провайдера й задайте цю змінну в терміналі.

Чи використовує Codex HTTPS_PROXY?
Так. Під час тесту в Codex 0.162.1 запити проходили через HTTPS_PROXY, а до хостів зі списку NO_PROXY проксі не застосовувався. Файли PAC не підтримуються.

Чому model_provider ігнорується у файлі .codex/config.toml мого проєкту?
Файли проєкту не можуть змінювати місце надсилання запитів, тож репозиторій не може перенаправляти ваш трафік. Укажіть провайдера у ~/.codex/config.toml; у файлі проєкту й надалі можна задавати модель.

Джерела

• Основи конфігурації, OpenAI
• Розширена конфігурація, OpenAI
• Довідник із конфігурації, OpenAI
• Посібник з інтеграції Codex CLI, AIHubMix
• Налаштування проксі для Codex CLI: SOCKS, HTTP і корпоративні мережі, Daniel Vaughan