config.toml і профілі Codex: 6 шарів пріоритету та заборонені ключі проєкту

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

Коротко (TL;DR)

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

• Файл не один, а кілька. Користувацький ~/.codex/config.toml, проєктний .codex/config.toml усередині репозиторію та системний /etc/codex/config.toml. Профіль — теж окремий файл.
• Шарів пріоритету шість. Згори прапорці командного рядка, знизу вбудовані значення за замовчуванням. Проєктний конфіг стоїть ВИЩЕ за профіль — і майже всі провідники у видачі кажуть протилежне.
• Профіль — це файл ~/.codex/<імʼя>.config.toml, увімкнути його можна прапорцем --profile <імʼя>. Старі таблиці [profiles.імʼя] всередині спільного конфігу знято у версії 0.134.0 від 26 травня 2026 року.
• Рядок profile = "імʼя", що лишився з минулих версій, узагалі не дає CLI запуститися — це найдорожча помилка в темі, і провідники про неї не пишуть.
• Проєктний конфіг урізаний свідомо. Десять ключів він не перевизначає ніколи: провайдер, базові URL, повідомлення, телеметрія, вибір профілю. Інакше склонований чужий репозиторій тихо відводив би ваші запити та API-ключ на чужий endpoint.
• Доступ задається двома несумісними способами — новими профілями дозволів або старою парою sandbox_mode/sandbox_workspace_write. Документація забороняє змішувати їх в одному файлі.

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

Де лежить config.toml і які три файли читає Codex

Почнемо з питання «де файл», бо плутанина починається вже тут: файл не один.

BINANCE COPY TRADINGКопітрейдинг на BinanceВідкрита статистика трейдерів, старт з $10, вимкнення одним кліком.Обрати трейдера

• Користувацький — ~/.codex/config.toml. Ваші особисті налаштування для всіх проєктів. Тека зʼявляється після встановлення Codex CLI; у Windows це %USERPROFILE%\.codex\. Теку цілком переносить змінна середовища CODEX_HOME — зручно, коли конфіг лежить у дотфайлах.
• Проєктний — .codex/config.toml усередині репозиторію. Командні домовленості, які їдуть разом із кодом. Codex іде від кореня проєкту вниз до вашої поточної теки й підбирає кожен знайдений файл; найближчий до теки головніший. Важливе застереження: цей шар читається лише в довіреного проєкту, про довіру — окремий розділ нижче.
• Системний — /etc/codex/config.toml на Unix-машинах, якщо він там є. Це рівень адміністратора, а не розробника.
• Файл профілю — ~/.codex/<імʼя>.config.toml, поряд з основним конфігом. Він не заміняє користувацький конфіг, а накладається на нього.

Два практичні нюанси, на яких спотикаються навіть досвідчені.

Оточення хмарних завдань Codex: setup-скрипт, кеш і доступ до інтернету

MCP-сервери в Codex: config.toml, транспорти і чому сервер не відповідає

Сесія Codex CLI на годину роботи: команди, витрата контексту й відкат через git

Codex CLI проти Codex Cloud: десять критеріїв вибору під завдання

DeepSeek Harness вийшов під MIT: відкрита обв’язка ІІ-агентів і реліз V4-Pro

Порядок рядків у TOML має значення. Ключі верхнього рівня (model, approval_policy, sandbox_mode) зобовʼязані стояти ДО першої таблиці в квадратних дужках. Якщо ви дописали model = "..." у кінець файлу після блоку [model_providers.proxy], TOML прочитає цей рядок як ключ усередині таблиці провайдера, а не як налаштування моделі. Помилка виглядає як «конфіг не застосувався».

Редактор умію підказувати ключі. Додайте першим рядком файлу посилання на офіційну JSON-схему конфігу — і VS Code або Cursor почнуть дописувати імена ключів та підсвічувати друкарські помилки:

#:schema https://developers.openai.com/codex/config-schema.json

model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"

Схема жива: на 11 серпня 2026 року вона віддається за цією адресою у форматі JSON Schema draft-07 і містить визначення на кшталт ConfigProfile, AskForApproval та HooksToml. Жоден розбір із першої десятки видачі про цей рядок не згадує, хоч він економить більше часу, ніж будь-який готовий шаблон.

І відразу розмежування, без якого далі буде каша. У проєкті поряд лежить другий файл — AGENTS.md. Він про те, що агентові знати про ваш проєкт: якою командою запускати тести, куди не лізти, у якому стилі писати код. config.toml — про те, як запускати самого агента: модель, глибина міркувань, права, провайдер. Інструкції — в AGENTS.md, середовище — в config.toml. Ключ project_doc_max_bytes (за замовчуванням 32 768 байтів, тобто 32 KiB) — єдине місце, де ці два файли стикаються: він обмежує, скільки тексту інструкцій Codex вчитує.

Шість шарів пріоритету: який конфіг Codex перебиває який

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

У корпоративному встановленні згори додається ще один рівень — адміністративні вимоги у requirements.toml, які користувацькі шари перебити не можуть. На особистій машині його зазвичай немає.

BINANCEДосі дивишся збоку?Ринок працює без вихідних. Рахунок на Binance відкривається за 2 хвилини.Почати зараз

Тепер найнеприємніше. Рядки 2 і 3 у популярних провідниках переставлені місцями, причому в обидва боки: один відомий розбір ставить профіль вище за проєктний конфіг, інший — нижче («між користувацьким і проєктним»), третій узагалі твердить, що проєктні налаштування перемагають завжди, і не згадує прапорців CLI. Офіційний довідник ставить проєктний конфіг вище за профіль, і в спірній ситуації я опираюся на нього, а не на переказ. Практичний висновок із цієї розбіжності важливіший за сам порядок: перевіряйте результат на своїй машині, а не спирайтеся на ланцюжок зі статті — як саме, розберемо в розділі про перевірку.

Одноразове перевизначення робиться прапорцем -c (він же --config), приймає пару в синтаксисі TOML і повторюється скільки потрібно:

codex -c model_reasoning_effort="high" -c sandbox_mode="read-only" "перевір міграції"

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

Ключі config.toml, які справді змінюють поведінку агента

Ключів у взірцевому конфігу понад тисячу рядків, але поведінку вирішують кілька. Значення та стандартні величини — з офіційного довідника ключів, зверено 11 серпня 2026 року.

Що варто тримати в голові щодо трьох найходовіших ключів.

model і model_reasoning_effort — пара, а не два незалежні перемикачі. Дешева модель з xhigh і дорога з low дають різний результат за схожого рахунку. Яку модель брати під яке завдання, розібрано окремо в матеріалі про вибір моделі Codex; тут важливо, що обидва ключі можна закріпити за сценарієм через профіль і не торкатися руками.

sandbox_mode та approval_policy — два різні регулятори. Перший задає, що агентові взагалі доступно; другий — коли він запитає дозволу. Сенс кожного значення та безпечні комбінації докладно розібрані в матеріалі про режими схвалення та пісочницю Codex — у цьому уроці я показую лише те, як записати їх у файл.

model_provider упирається в аутентифікацію. Блок провайдера обʼявляється так:

model = "your-model-id"
model_provider = "custom_provider"

[model_providers.custom_provider]
name = "Custom Provider"
base_url = "https://api.example.com/v1"
env_key = "CUSTOM_API_KEY"
wire_api = "responses"

Ключ env_key — імʼя змінної середовища, з якої береться API-ключ; сам ключ у файл не пишемо ніколи. Як Codex узагалі отримує доступ — через вхід у ChatGPT чи через API-ключ — розібрано в матеріалі про аутентифікацію Codex. Вбудованих провайдерів три: openai, ollama та lmstudio, останні два — для локальних моделей.

Окремо про MCP: підключення зовнішніх інструментів і сервісів теж обʼявляється в цьому файлі, блоками [mcp_servers.<імʼя>] з транспортом stdio або streamable HTTP. Тема велика й заслуговує на свій розбір — розбираємо окремо в уроці про MCP у Codex, тут достатньо знати, що механізм живе в тому самому config.toml і підлягає тим самим шести шарам пріоритету.

Іменовані профілі Codex: окремий файл на кожен сценарій

Профіль — це іменований набір налаштувань під сценарій роботи. Механіка станом на 11 серпня 2026 року така:

1. Створіть файл ~/.codex/<імʼя>.config.toml поряд з основним конфігом. Імʼя допускає літери, цифри, дефіс і підкреслення: deep-review, ci, quick.
2. Пишіть у нього ключі верхнього рівня — так само, як в основному конфігу. Жодних [profiles.deep-review]: офіційна документація прямо просить не вкладати ключі під таку таблицю.
3. Перелічіть лише те, що відрізняється. Решту профіль успадкує з ~/.codex/config.toml.
4. Увімкніть прапорцем codex --profile deep-review (коротка форма -p). Працює й з неінтерактивним запуском: codex exec --profile ci "проженi тести".

Файл профілю виглядає буденно — і це правильно:

model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"

Три рядки, бо решта двадцять налаштувань уже лежать у базовому конфігу й змінювати їх для цього сценарію не потрібно.

Що важливо знати про ввімкнення: воно завжди явне. Автоматичного «профілю за замовчуванням» через рядок у конфігу більше немає — про це докладно в розділі про поломки. Частина сторонніх провідників згадує змінну середовища CODEX_PROFILE; в офіційному довіднику ключів та в опису профілів її немає, тому в CI я закладаю прапорець --profile, а не змінну.

Три готові профілі: швидкі правки, рефакторинг, ревю без запису

Нижче — три конфіги, які можна скопіювати відразу. Кожен ключ підібраний під сценарій, а не «для повноти».

Профіль 1 — швидкі правки. Друкарська помилка, перейменування, дрібний фікс. Міркувати глибоко не потрібно, чекати не хочеться, писати в робочу теку — можна.

model_reasoning_effort = "low"
model_verbosity = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
personality = "pragmatic"

Чому так: low на міркуваннях і докладності — бо завдання механічне, і високий рівень тут лише збільшує рахунок і час. on-request залишає агента самостійним усередині пісочниці, але зупиняє перед виходом за її межі. cached тримає пошук на індексі OpenAI без виходу в інтернет — для правки друкарської помилки живий пошук не потрібен.

Профіль 2 — важкий рефакторинг. Багато файлів, неочевидні звʼязки, ціна помилки висока.

model_reasoning_effort = "xhigh"
model_verbosity = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
writable_roots = []
network_access = false

Чому так: xhigh — єдине місце, де максимальне усилля виправдане рахунком. model_verbosity = "low" водночас залишає вивід коротким: міркувати глибоко й переказувати багатослівно — різні речі. network_access = false явно фіксує, що рефакторинг не ходить у мережу (у режимі workspace-write мережа й так вимкнена за замовчуванням, але в профілі, який поїде в команду, краще написати це явно). writable_roots — список додаткових шляхів, куди дозволено запис поза робочою текою; порожній список означає «лише робоча тека».

Профіль 3 — ревю без запису. Агент читає код і пише висновок, але не змінює жодного байта.

model_reasoning_effort = "high"
approval_policy = "never"
sandbox_mode = "read-only"
web_search = "cached"

Чому так: read-only фізично забороняє запис, тому approval_policy = "never" тут безпечний — питати нема про що, зіпсувати нічого, а робота йде без зупинок. Це єдина комбінація з трьох, де never доречний: із правом запису він означав би «роби що хочеш, не питаючи». Пара значень та сама, що в розборі режимів у сценарії неінтерактивного запуску в CI, — і це не випадковість: сценарії різні (там сенс режимів, тут оформлення їх у профіль), а безпечна комбінація для роботи без питань і без запису одна.

Запуск, відповідно: codex -p quick, codex -p deep, codex -p review. Одне зауваження: у всіх трьох профілях доступ заданий через sandbox_mode. Якщо ви перейшли на профілі дозволів, ці рядки в них писати не можна — чому, нижче.

Чому проєктний .codex/config.toml не змінить вам провайдера

Проєктний конфіг виглядає всесильним: він стоїть другим шаром згори й перебиває користувацькі налаштування. Але має два запобіжники.

Перший — довіра. Проєктні шари .codex/ (а разом із конфігом це ще хуки та правила) читаються лише в проєкту, який ви позначили довіреним; рішення зберігається у вашому користувацькому конфігу як trust_level у блоці [projects]. У версії 0.147.0 від 7 серпня 2026 року вимогу явної довіри для незнайомих локальних проєктів додатково посилили. Практичний сенс: «довіряю» для чужого репозиторію — це не формальність, а рішення щодо безпеки, і ухвалювати його варто після читання того, що в .codex/ лежить.

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

Логіка заборони читається з одного погляду на таблицю. Якби репозиторій міг задати model_provider і base_url, то достатньо було б склонувати чужий проєкт — і ваші запити разом із ключем з env_key пішли б на чужий endpoint, а ви цього не помітили б: агент працює, відповіді надходять. Якби він міг задати notify, то отримав би право запускати довільну команду на вашій машині за подією. Саме тому межа проведена не за принципом «зручно чи ні», а за принципом «хто платить і хто володіє секретами». Це не обмеження заради обмеження, а єдине місце у файлі, де рішення ухвалене за вас — і ухвалене правильно.

Одне застереження щодо поверхонь: проєктні дозволи на різних клієнтах Codex поводяться неоднаково. У трекері є відкрита заявка про те, що настільний застосунок Codex не застосовує проєктний default_permissions з .codex/config.toml. Висновок робочий: якщо налаштування критичне для безпеки, не спирайтеся на те, що всі клієнти прочитають його однаково, — перевіряйте на тій поверхні, де працюєте.

Доступ у config.toml задають двома способами, і змішувати не можна

У файлі співіснують дві системи прав, і це головна пастка при копіюванні чужих прикладів.

Стара пара — sandbox_mode плюс уточнювальний блок [sandbox_workspace_write] (writable_roots, network_access, винятки для /tmp і $TMPDIR). Саме її ви бачили у трьох профілях вище.

Нова система — профілі дозволів: ключ default_permissions називає активний профіль, а самі профілі обʼявляються таблицями [permissions.<імʼя>] з розділами filesystem і network. Вбудованих профілів три: :read-only (локальні команди лише читають), :workspace (запис усередині робочих коренів і системної тимчасової теки) та :danger-full-access (локальна пісочниця знімається). Власний профіль зручно нарощувати від вбудованого через extends:

default_permissions = "workspace-net"

[permissions.workspace-net]
extends = ":workspace"

[permissions.workspace-net.network.domains]
"api.openai.com" = "allow"

Успадковуватися від :danger-full-access Codex не дає, невідомих батьків і цикли в успадкуванні теж відкидає — тобто «розширити повний доступ» через профіль не вийде.

А тепер правило, якого немає в жодному розборі з видачі. Документація Codex каже буквально: профілі дозволів не поєднуються зі старими налаштуваннями пісочниці, налаштовуйте або default_permissions і [permissions], або sandbox_mode і sandbox_workspace_write, але не обидва. Це означає, що типовий «збірний» конфіг із чужого провідника, де поряд стоять default_permissions = ":workspace" і sandbox_mode = "workspace-write", — не «налаштування із запасом», а файл із невизначеною поведінкою. Обирайте одну систему на весь конфіг і всі його профілі.

Як перевірити, які налаштування Codex застосував насправді

Шість шарів — це шість місць, де ваше налаштування могло загубитися. Порядок перевірки, від дешевого до дорогого:

1. Прочитайте попередження на старті. Заборонений ключ у проєктному конфігу, зламаний TOML, знятий синтаксис — Codex повідомляє про це в перших рядках виводу. Їх звично промотують.
2. Запитайте сесію. Slash-команда /status показує конфігурацію поточної сесії; це найшвидший спосіб побачити, яка модель і які права справді активні. Вона та решта команд керування сесією розібрані в матеріалі про робочий цикл Codex CLI.
3. Перевірте гіпотезу прапорцем. Запустіть те саме завдання з -c ключ="значення". Поведінка змінилася — отже, ключ правильний, а ваш файл перебиває шар вище або лежить не там. Не змінилася — річ не в цьому ключі.
4. Переконайтеся, що профіль узагалі підхопився. Імʼя в --profile має збігатися з імʼям файлу: --profile deep читає ~/.codex/deep.config.toml. Друкарська помилка в імені — найчастіша причина «профіль не працює».
5. Перевірте, що дивитеся в той файл. Якщо задана змінна CODEX_HOME, ваш конфіг лежить не в ~/.codex/, а там, куди вона вказує.

Ризики config.toml: знятий синтаксис профілів і тихі відмови

Чотири з пʼяти проблем нижче дають не повідомлення про помилку, а неправильну поведінку — тому розділ варто прочитати до того, як правити файл.

Рядок profile = "імʼя" не дає CLI запуститися. З релізу 0.134.0 від 26 травня 2026 року прапорець --profile став єдиним способом обрати профіль: таблиці [profiles.імʼя] усередині спільного конфігу та селектор profile = "імʼя" більше не підтримуються. Відмова жорстка — не попередження, а помилка завантаження конфігурації, після якої Codex не стартує. Текст помилки прямо називає і проблему, і лікування: legacy profile = "openai-chatgpt" config is no longer supported; use --profile openai-chatgpt with openai-chatgpt.config.toml instead. Заявка #24858 у трекері Codex станом на 11 серпня 2026 року досі відкрита, і головна претензія в ній справедлива: оновлення ламає інструмент, яким лише й можна було б виправити конфіг.

Міграція займає хвилину:

1. Видаліть рядок profile = "імʼя" з ~/.codex/config.toml.
2. Перенесіть вміст таблиці [profiles.імʼя] у новий файл ~/.codex/імʼя.config.toml — ключами верхнього рівня, без обгортки.
3. Видаліть саму таблицю [profiles.імʼя] з основного конфігу й запускайте з --profile імʼя.

Приклади з першої десятки видачі вчать знятого синтаксису. Я розібрав шість матеріалів із першої десятки за ключовими фразами теми, включно з найпомітнішими, і станом на 11 серпня 2026 року всі шість показують профілі як таблиці [profiles.імʼя] всередині config.toml — окремого файлу профілю не показує жоден із цієї шістки. Виняток є, і він показовий: незалежний розбір від 19 липня 2026 року вже оновився — він рекомендує саме окремі файли на кшталт ~/.codex/review.config.toml і прямо попереджає не копіювати [profiles.review] зі старих прикладів. Тобто відставання провідників не всеосяжне, але у верхніх результатах переважає. Копіювання застарілого прикладу дає не «трохи застарілий», а неробочий конфіг — а якщо в прикладі є ще й рядок profile =, то й неробочий Codex. Це і є ціна релізу 0.134.0, про який у провідниках не написано.

Заборонені ключі ігноруються тихо. Попередження на старті є, але налаштування у файлі залишається видимим і виглядає застосованим. Читаючи проєктний .codex/config.toml, помʼятайте: model_provider у ньому — мертвий рядок.

Дві системи прав в одному файлі дають невизначений доступ. Розібрано вище: або профілі дозволів, або sandbox_mode.

Довіра проєкту вмикає більше, ніж конфіг. Разом із ним піднімаються проєктні хуки та правила. Позначаючи чужий репозиторій довіреним, ви погоджуєтеся на весь вміст .codex/, а не лише на модель і права.

Прапорці живуть недовго. У версії 0.147.0 від 7 серпня 2026 року видалено застарілий прапорець --full-auto — замість нього --sandbox workspace-write. Значення approval_policy = "on-failure" теж позначене застарілим. Конфіг, зашитий у CI за минулорічним провідником, ламається саме на такому оновленні.

Що в конфігу Codex застаріє першим: імена ключів і прапорці

Codex змінюється швидко, і за релізами це видно: 0.134.0 (26 травня 2026) зніс профілі старого формату, 0.147.0 (7 серпня 2026) прибрав прапорець --full-auto й посилив вимогу довіри; станом на 11 серпня 2026 року в ленті вже лежить альфа 0.148.0.

Що старіє першим:

• Імена та склад моделей у ключі model — старіють найшвидше.
• Імена прапорців і значень (--full-auto, on-failure) — знімаються між версіями.
• Стандартні величини пісочниці та схвалень. Тут джерела розходяться вже зараз: офіційний взірець конфігу містить sandbox_mode = "read-only" та approval_policy = "on-request", незалежні розбори називають стандартною величиною workspace-write, а довідник ключів фіксованої стандартної величини не друкує взагалі. Це не причина вгадувати: подивіться /status на своїй версії.
• Склад [features] — прапорці зʼявляються й увімкуються за замовчуванням.

Що старіє повільно й на що можна спиратися: розташування файлів, шестишарова модель пріоритету, розділення «інструкції в AGENTS.md, середовище в config.toml» і список ключів, заборонених для проєктного шару. Зверятися варто не з провідниками, а з довідником ключів і лентою релізів — і перечитувати їх під час мажорного оновлення, а не після того, як CLI перестав запускатися.

FAQ

Де лежить config.toml, якщо після встановлення Codex файлу немає? Codex не створює файл сам — порожній конфіг рівнозначний вбудованим значенням за замовчуванням. Створіть ~/.codex/config.toml руками (у Windows — %USERPROFILE%\.codex\config.toml). Тека ~/.codex зʼявляється під час першого запуску й зберігає ще й історію сесій, і логи. Якщо задана змінна CODEX_HOME, файл треба покласти в указану нею теку.

Чи можна тримати різні моделі та різний рівень міркувань для різних проєктів? Так, двома способами. Перший — проєктний .codex/config.toml у репозиторії: ключі model і model_reasoning_effort він перевизначати має право, і це поїде разом із кодом усій команді. Другий — іменований профіль під тип завдання та запуск codex --profile deep. Перший привʼязаний до теки, другий — до сценарію роботи.

Чому Codex перестав запускатися після оновлення й пише про legacy profile? У вашому ~/.codex/config.toml лишився рядок profile = "імʼя". З версії 0.134.0 він не підтримується, і Codex не стартує. Видаліть його, перенесіть вміст таблиці [profiles.імʼя] в окремий файл ~/.codex/імʼя.config.toml ключами верхнього рівня й запускайте з прапорцем --profile імʼя.

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

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

Чи може чужий репозиторій через .codex/config.toml відвести мій API-ключ? Ні, і це зроблено свідомо. Проєктний шар читається лише в довіреного проєкту й узагалі не приймає ключів model_provider, model_providers, openai_base_url і chatgpt_base_url — підмінити endpoint із репозиторію не можна. Але довіра піднімає ще проєктні хуки та правила, тому вміст .codex/ у чужому репозиторії варто прочитати до того, як натиснути «довіряю».