Codex config.toml instellen: aangepaste API, proxy en veelvoorkomende fouten

Codex bewaart de instellingen in één bestand, config.toml: welk model je gebruikt, welke API je aanroept en hoeveel de agent mag doen zonder het te vragen. De indeling is in 2026 meerdere keren gewijzigd en in veel handleidingen van eerder dat jaar staan instellingen waardoor Codex nu niet meer start.

Deze handleiding begint met een werkende configuratie en behandelt daarna de onderdelen die de meeste mensen aanpassen: profielen, projectinstellingen, de sandbox en een proxy. Tot slot volgt een lijst met fouten die je waarschijnlijk tegenkomt, met uitleg bij elke fout. Gecontroleerd aan de hand van de documentatie van OpenAI en getest met Codex CLI 0.162.1 op 19 oktober 2026. De voorbeelden gebruiken AIHubMix als provider; elke gateway die de OpenAI Responses API ondersteunt, werkt op dezelfde manier.

Kort samengevat

• Het bestand staat in ~/.codex/config.toml of op Windows in C:\Users\<you>\.codex\config.toml.
• Voor een aangepaste provider heb je base_url, wire_api = "responses" en env_key nodig. De API-sleutel zet je in een omgevingsvariabele.
• Profielen staan nu in afzonderlijke bestanden, ~/.codex/<name>.config.toml, die je selecteert met --profile <name>.
• Een bestand .codex/config.toml in een repository werkt alleen in vertrouwde projecten en kan de provider niet wijzigen.
• Start Codex na elke wijziging opnieuw op; het bestand wordt alleen bij het opstarten ingelezen.

Waar config.toml staat

Je hoofdinstellingen staan in ~/.codex/config.toml. Zowel de CLI als de IDE-extensie lezen dit bestand. Bestaat het nog niet, maak het dan aan.

Twee andere locaties kunnen hier instellingen aan toevoegen:

• Profielbestanden, ~/.codex/<name>.config.toml, die alleen worden gebruikt als je Codex start met --profile <name>.
• Projectbestanden, .codex/config.toml in een repository, voor instellingen die een team wil delen.

Als je Codex in WSL2 op Windows uitvoert, gebruikt het de Linux-thuismap (/home/<you>/.codex/config.toml), niet de Windows-map. Als CODEX_HOME is ingesteld, gebruikt Codex die map in plaats van ~/.codex.

Een minimale werkende configuratie

Dit volledige bestand ~/.codex/config.toml stuurt de verzoeken van Codex naar 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 is de model-ID die wordt aangeroepen en model_reasoning_effort is het standaardniveau voor redeneren.
• model_provider moet overeenkomen met de naam in [model_providers.<name>]. Gebruik niet openai, ollama of lmstudio; die namen zijn gereserveerd voor de ingebouwde providers van Codex.
• base_url is het API-adres van de provider. wire_api = "responses" is nu de enige waarde die Codex accepteert.
• env_key is de naam van een omgevingsvariabele, niet de sleutel zelf.

Stel die variabele vervolgens in met een sleutel uit de AIHubMix-console:

# 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-..."

Start codex vanuit een nieuwe terminal en stel een vraag. Als Codex antwoordt, werkt de provider. Of je bij Codex bent ingelogd, maakt hier niet uit: de sleutel van codex login wordt nooit naar een aangepaste provider gestuurd.

Profielen: één bestand per configuratie

Een profiel bevat alleen instellingen die afwijken van je hoofdconfiguratie, zoals uitgebreider redeneren en een alleen-lezen-sandbox voor codebeoordeling. Elk profiel is een eigen bestand naast config.toml, met de sleutels op het hoogste niveau:

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

codex --profile review

Dit is gewijzigd in Codex 0.134.0. In oudere handleidingen staan profielen in config.toml als tabellen van het type [profiles.review], die je selecteert met profile = "review". Codex weigert nu met die selectieregel op te starten. Een overgebleven tabel [profiles.review] op zichzelf wordt zonder melding genegeerd, waardoor de instellingen ongemerkt niet meer werken. Om over te stappen, verplaats je de sleutels van elke tabel naar ~/.codex/<name>.config.toml en verwijder je vervolgens de tabel en de regel profile = .... Meer informatie vind je in de geavanceerde configuratiehandleiding van OpenAI.

Projectconfiguratie: .codex/config.toml

Met een bestand .codex/config.toml in een repository kan een team een standaardmodel, redeneerniveau of sandboxmodus delen. Codex leest het alleen in projecten die in je eigen bestand ~/.codex/config.toml als vertrouwd zijn gemarkeerd:

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

Een projectbestand kan niet wijzigen waar verzoeken naartoe worden gestuurd. Codex negeert daar model_provider, model_providers, openai_base_url, profile, notify en enkele andere sleutels, en geeft daarbij een waarschuwing. Stel je provider in ~/.codex/config.toml in. Een project kan nog steeds het model kiezen; het verzoek gaat dan naar je eigen provider.

Welke instelling heeft voorrang?

Als dezelfde sleutel op meerdere plekken is ingesteld, geldt volgens de basisinformatie over configuratie van OpenAI de volgende volgorde, van hoogste naar laagste prioriteit:

1. Opdrachtregelopties, waaronder overschrijvingen met -c
2. Het projectbestand .codex/config.toml
3. Het profiel dat je met --profile selecteert
4. Je bestand ~/.codex/config.toml
5. De systeemconfiguratie, /etc/codex/config.toml
6. De ingebouwde standaardinstellingen van Codex

Let op: een projectbestand heeft voorrang op een profiel. Als een profielinstelling niets lijkt te doen, controleer dan of het bestand .codex/config.toml van de repository dezelfde sleutel instelt.

Gebruik -c om een instelling voor één uitvoering te wijzigen:

codex -c model_reasoning_effort=high

Sandbox en goedkeuringen

Twee sleutels bepalen wat Codex zelfstandig doet. Met sandbox_mode stel je in wat de opdrachten mogen benaderen; met approval_policy bepaal je wanneer Codex stopt om je iets te vragen.

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

[sandbox_workspace_write]
network_access = true   # off by default

Deze twee instellingen staan los van elkaar: never voorkomt vragen, maar maakt de sandbox niet minder strikt. In workspace-write hebben opdrachten geen toegang tot het netwerk, tenzij je network_access = true instelt.

Een proxy gebruiken

Codex heeft geen proxy-instelling in config.toml. Het gebruikt de standaardomgevingsvariabelen:

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

De documentatie van OpenAI vermeldt deze variabelen niet, dus zijn ze getest met Codex 0.162.1: verzoeken, ook naar een aangepaste provider, liepen via HTTPS_PROXY (of ALL_PROXY), terwijl hosts in NO_PROXY rechtstreeks werden benaderd. PAC-bestanden worden niet ondersteund, dus vul het proxyadres zelf in. Als de proxy van je bedrijf een eigen rootcertificaat gebruikt, stel dan CODEX_CA_CERTIFICATE in op dat certificaat, zoals beschreven in de referentie voor omgevingsvariabelen.

Meer modellen in /model

De modelkiezer /model toont alleen modellen van OpenAI. Als je daarin GLM-, Claude-, Gemini- of DeepSeek-modellen wilt kiezen, voeg je een modelcatalogus toe: een JSON-bestand dat wordt aangegeven met de sleutel model_catalog_json op het hoogste niveau. Zet die sleutel vóór de eerste regel [table]; anders beschouwt TOML hem als onderdeel van die tabel en negeert Codex hem.

De catalogus vervangt de ingebouwde lijst en elke vermelding moet een lange reeks velden bevatten, dus je kunt hem het beste laten genereren in plaats van hem handmatig te schrijven. De handleiding voor AIHubMix Codex CLI bevat een script dat een catalogus samenstelt op basis van de 30 populairste modellen op AIHubMix. De desktop-app verbergt aangepaste modellen mogelijk nog steeds in de modelkiezer (openai/codex#19694), dus wissel in dat geval van model in de terminal.

Veelvoorkomende fouten en hun betekenis

Dit zijn de meldingen die Codex 0.162.1 bij elke fout liet zien.

legacy profile = "..." config is no longer supported
In je config.toml staat nog de oude regel profile = "...". Verplaats het profiel naar een eigen bestand, zoals hierboven beschreven. Als je --profile x uitvoert terwijl er nog een oude tabel [profiles.x] bestaat, krijg je een vergelijkbare foutmelding: --profile x cannot be used while ... contains legacy ... config.

wire_api = "chat" is no longer supported
Codex ondersteunt de Chat Completions API niet meer. Wijzig dit in wire_api = "responses". Een provider die alleen Chat Completions aanbiedt, werkt niet zonder een proxy die de API vertaalt.

model_providers contains reserved built-in provider IDs
Je hebt je provider openai, ollama of lmstudio genoemd. Geef de tabel en model_provider een andere naam.

approval_policy = "untrusted" is no longer supported
Verwijder de regel of gebruik on-request.

Missing environment variable: AIHUBMIX_API_KEY
De variabele die bij env_key is genoemd, is niet ingesteld in de terminal waarmee Codex is gestart. Open een nieuwe terminal of voer source ~/.zshrc uit en start Codex opnieuw.

401 Unauthorized na enkele regels met "Reconnecting..."
Het verzoek is zonder sleutel verstuurd. Controleer of de providertabel env_key bevat. De aanmelding in auth.json telt niet voor aangepaste providers.

Model metadata for ... not found. Defaulting to fallback metadata
Codex heeft geen ingebouwde instellingen voor dit model. Dat is normaal voor modellen die niet van OpenAI zijn. Verzoeken werken nog steeds. Voeg een modelcatalogus toe als je de juiste instellingen wilt gebruiken en het model in /model wilt zien.

Ignored unsupported project-local config keys
In het bestand .codex/config.toml van een repository staat een sleutel die alleen in je eigen configuratie werkt, meestal model_provider. Verplaats die naar ~/.codex/config.toml.

missing field base_instructions
Een vermelding in je modelcatalogus mist een verplicht veld, dus weigert Codex het hele bestand. Genereer de catalogus opnieuw met het script in plaats van hem handmatig aan te passen.

Als een instelling geen effect heeft

• Start Codex opnieuw op nadat je wijzigingen hebt aangebracht.
• Zorg dat sleutels op het hoogste niveau vóór de eerste regel [table] staan.
• Controleer het bestand .codex/config.toml van de repository; het heeft voorrang op je profiel.
• Controleer of er nog een tabel [profiles.x] staat.
• Voer codex doctor uit om je installatie, configuratie en aanmelding te controleren.

Als je OpenAI-, Anthropic-, Google-, Zhipu-, DeepSeek- en andere modellen in Codex met één sleutel wilt gebruiken, biedt AIHubMix ze aan via de Responses API op https://aihubmix.com/v1. Begin met de minimale configuratie hierboven en voeg een modelcatalogus toe als je via /model van model wilt kunnen wisselen.

Veelgestelde vragen

Waar staat het Codex config.toml-bestand?
Op macOS en Linux in ~/.codex/config.toml en op Windows in C:\Users<you>.codex\config.toml. Als CODEX_HOME is ingesteld, staat het bestand in die map.

Moet ik Codex opnieuw starten nadat ik config.toml heb gewijzigd?
Ja. Codex leest het bestand wanneer het opstart, dus sluit de terminalsessie of app af en open die opnieuw.

Waarom zegt Codex dat ‘legacy profile config is no longer supported’?
Codex 0.134.0 heeft profielen die in config.toml zijn gedefinieerd niet langer ondersteund. Verplaats elk profiel naar ~/.codex/name.config.toml, verwijder de oude regels en start Codex met --profile name.

Kan ik wire_api = "chat" nog steeds gebruiken?
Nee. Codex accepteert alleen wire_api = "responses". Een provider die alleen Chat Completions ondersteunt, heeft een proxy nodig die dit omzet naar de Responses API.

Waarom geeft mijn aangepaste provider een 401-foutmelding terwijl ik ben ingelogd bij Codex?
De inlogsleutel in auth.json wordt niet naar aangepaste providers gestuurd. Voeg env_key toe aan de providertabel en stel die variabele in je terminal in.

Gebruikt Codex HTTPS_PROXY?
Ja. In een test met Codex 0.162.1 liepen verzoeken via HTTPS_PROXY en werden hosts in NO_PROXY overgeslagen. PAC-bestanden worden niet ondersteund.

Waarom wordt model_provider genegeerd in de .codex/config.toml van mijn project?
Projectbestanden kunnen niet bepalen waar verzoeken naartoe gaan, zodat een repository je verkeer niet kan omleiden. Zet de provider in ~/.codex/config.toml; het projectbestand kan nog steeds het model instellen.

Bronnen

• Basisbeginselen van configuratie, OpenAI
• Geavanceerde configuratie, OpenAI
• Naslaginformatie over configuratie, OpenAI
• Integratiehandleiding voor Codex CLI, AIHubMix
• Proxyconfiguratie voor Codex CLI: SOCKS, HTTP en bedrijfsnetwerken, Daniel Vaughan