Как да настроите 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 или C:\Users\<you>\.codex\config.toml в Windows.
• За персонализиран доставчик са нужни 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 е ID на модела, към който се изпраща заявката, а model_reasoning_effort задава стандартното му ниво на разсъждение.
• model_provider трябва да съвпада с името в [model_providers.<name>]. Не използвайте openai, ollama или lmstudio — тези имена са запазени за вградените доставчици на Codex.
• base_url е API адресът на доставчика. wire_api = "responses" е единствената стойност, която Codex приема вече.
• 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 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 вече не поддържа Chat Completions API. Променете стойността на 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, който проверява инсталацията, конфигурацията и данните за вход.

Ако искате да използвате OpenAI, Anthropic, Google, Zhipu, DeepSeek и други модели в Codex с един ключ, AIHubMix ги предоставя чрез Responses API на адрес https://aihubmix.com/v1. Започнете с минималната конфигурация по-горе и добавете каталог с модели, когато искате да превключвате между моделите от /model.

Често задавани въпроси

Къде се намира файлът Codex config.toml?
В ~/.codex/config.toml в macOS и Linux, а в C:\Users<you>.codex\config.toml в Windows. Ако е зададена CODEX_HOME, файлът се намира в тази папка.

Трябва ли да рестартирам Codex след промяна на config.toml?
Да. Codex прочита файла при стартиране, затова затворете и отворете отново терминалната сесия или приложението.

Защо Codex казва „legacy profile config is no longer supported“?
В 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