Agent creation and model updates
This page explains the protocol for creating an agent in the bundled default configuration, importing its developer messages, and the companion maintenance a model update needs (model catalog, pricing, docs, tests).
The bundled default configuration lives in
agent_terminal_app/default_config/. config.json is the maintained source;
site preparation generates /reference/default-config/ from it. Run the
documentation preparation and build after config changes when documentation
output is in scope.
Agent entries
An agent is an entry under agents in config.json. The smallest useful
entry names a provider, a model, and the plugins that supply its tools:
"codex-openai-api": {
"mixin_refs": ["codex_developer_message", "codex_mcp_defaults"],
"provider": "openai",
"model": "gpt-5.4",
"plugins": ["path:${env:BUILTIN_PLUGINS}/codex-tools"],
"auth_mode": "api",
"system_message_as_instructions": false
}
Mixin references (mixin_refs) pull in shared blocks from mixins. The
codex_developer_message mixin supplies the system-message template, the
developer-message selection table, and Codex personality/skills settings, so
Codex-family agents do not repeat them.
Two flags control how the compiled system message reaches the provider:
system_message_as_instructions: truesends it as the top-levelinstructionsfield of a Responses request and keeps it out of session history;falsekeeps it as a persistent native system message in the session.
System and developer messages
feature-system-message renders the configured system_message template for
each request from template variables (see
system-message configuration for the
general mechanism).
For Codex-family agents the flow is:
- The mixin's template
system_messages/codex/template.mdcombines{{CODEX_DEVELOPER_MESSAGE}},{{CODEX_PROJECT_INSTRUCTIONS}},{{CODEX_ENVIRONMENT_CONTEXT}}, and{{TASKS}}. {{CODEX_DEVELOPER_MESSAGE}}is produced bysystem_messages/helpers/select_codex_developer_message.py, which selects a row fromcodex_developer_messagesby matchingCONFIG["model"]againstmodel_regex(an optionalopenai/prefix is allowed) andCONFIG["codex_personality"]against the row'spersonalityfield. Rows without apersonalityfield match every personality through the fallback path.- Each row's
textloads the instruction asset with a${file:${env:CONFIG_DIR}/codex/<model>/...}placeholder.
The final .* row is the fallback for unknown models; add more specific rows
above it.
Importing Codex developer messages
Instruction text for Codex-family models is imported from the upstream
openai/codex repository, file
codex-rs/models-manager/models.json (historical path:
codex-rs/core/models.json). Each model entry's
model_messages.instructions_template is the instruction source; older
entries also carried base_instructions and personality
instructions_variables, which upstream has since removed.
Assets live under default_config/codex/<model-id>/, with reference copies
under
default_config/system_messages/reference/default-system-instructions/codex/<model-id>/.
default_config/codex/README.md records the upstream commit for each import.
Date-versioned developer message files
From 2026-09-14 onward, every newly imported developer-message version is stored in files whose names carry the date that version was introduced upstream:
instructions_default.YYYYMMDD.md— the effective developer message the config row points at;model_messages.instructions_template.YYYYMMDD.md— the raw upstream template;model_messages.instructions_variables.YYYYMMDD.json— the raw variables object, when upstream provides one;model_messages.persistent_instructions.YYYYMMDD.md— persistent-mode instructions, when upstream provides them (kept for provenance; not wired into config).
YYYYMMDD is the UTC date of the earliest upstream commit whose
codex-rs/models-manager/models.json contains exactly this instruction
text. Find it by walking the file's git history from newest to oldest and
comparing the template's sha256 at each commit: keep walking while the hash
matches; the oldest commit in that contiguous matching run — the last one
before the content changes or the model first appears — is the introducing
commit.
When a newer upstream version is imported later, add new date-versioned
files next to the previous ones and repoint the codex_developer_messages
row at the new instructions_default.YYYYMMDD.md. Keep previous version
files in place for provenance and rollback. Existing files that predate
this protocol keep their original names; do not rename or re-date them.
Placeholders in imported text:
{{ personality }}(older templates) is filled frominstructions_variablesper the personality rows;- non-personality placeholders that upstream renders literally, such as
{{connector_id}}in the GPT-6-Astra Apps (Connectors) syntax, are kept verbatim — they document user-message syntax, not a runtime substitution.
Companion maintenance for a model update
A new or changed model needs more than instruction assets. Do each of the following in the same change:
Model catalog snapshot
Refresh the checked-in Codex models snapshot used for ChatGPT-mode model discovery:
python plugins/openai_responses/benchmark/refresh_openai_responses_models.py
The snapshot replaces its previous content, so retired upstream models drop out and new models appear. See Model discovery.
Reasoning-effort gating in
openai_responses_reasoning_extension.py uses per-family model patterns; add
a pattern for a new model family so its real effort set is offered.
Pricing snapshot
Refresh the checked-in pricing snapshot from the official pricing pages:
python plugins/openai_responses/benchmark/refresh_openai_responses_pricing.py
The refresh merges page entries into the snapshot. The pricing pages label
the fast processing tier fast, and the snapshot keys it as fast; the
official API still reports the obsolete priority name in responses (and
the ChatGPT backend only accepts priority on requests), so the pricing
lookup normalizes priority → fast and Fast mode sends the wire value
the target endpoint accepts (fast for API auth, priority for ChatGPT
auth). See
Cost estimation.
Documentation and tests
- Update
default_config/codex/README.mdwith the import commit, dates, and family notes. - Run documentation preparation and the normal MkDocs build after
config.jsonchanges when generated documentation is in scope. - Add unit tests for model selection (model regex,
openai/prefix, personality fallback, content distinctions, older-model regressions) underapplication/python/tests/. - Prove end-to-end delivery with a real-API test (compiled instructions reach
the request) and, for ChatGPT auth, a
manual_integrationtest using the saved-login recording provider.