Allow custom instructions with experimental_instructions_file when using GPT‑5/Codex models
Resolved 💬 4 comments Opened Sep 29, 2025 by namastex888 Closed Oct 1, 2025
💡 Likely answer: A maintainer (pakrym-oai, contributor)
responded on this thread — see the highlighted reply below.
Summary
- Overriding the GPT-5 / GPT-5-Codex system prompt via
experimental_instructions_filetriggers the Responses API to return400 {"detail":"Instructions are not valid"}. - Codex currently replaces the built-in prompt entirely before sending the JSON payload,
so GPT-5 models never see the required baseline instructions.
- This blocks research workflows that rely on experimenting with alternate prompts.
### Steps to Reproduce
- From a Codex workspace containing an alternate prompt file (e.g.
custom_prompt.md),
run:
codex exec -c 'experimental_instructions_file="./codex-rs/core/gpt_5_codex_prompt.md"' "What is your identity?"
"What is your identity?"
This succeeds because it points at the original prompt.
- Repeat with any other file, for example:
codex exec -c 'experimental_instructions_file="./path/to/your/custom_prompt.md"' "What is your identity?"
### Actual Result
- Every streaming retry fails with stream error: unexpected status 400 Bad Request:
{"detail":"Instructions are not valid"} and the session aborts.
### Expected Result
- Codex should accept custom instructions for GPT-5-class models—ideally by keeping the canonical base prompt intact while appending the user-provided text, so researchers can explore alternate behaviors.
### Investigation Notes
- codex-rs/core/src/config.rs:993-1022 reads the file and currently replaces base_instructions wholesale.
- codex-rs/core/src/client_common.rs:24-63 then forwards that string as the instructions field in the Responses API payload.
- GPT-5 / GPT-5-Codex families pull from codex-rs/core/gpt_5_codex_prompt.md; replacing it appears to violate OpenAI’s validation.
### Possible Directions
- When the selected provider uses the Responses API and the model family starts with gpt-5 or gpt-5-codex, treat experimental_instructions_file as additional user instructions (append to the built-in prompt instead of replacing it).
- Alternatively, add a dedicated user_instructions_file config option that mirrors the existing AGENTS.md behavior without touching the base prompt.
Happy to help prototype either approach, please let me know if a PR along these lines would be welcome or if you have guidance on the preferred solution.
4 Comments
This is by design, custom instructions are supported when using the API key. You can use Agents.md to augment instructions when using the ChatGPT account.
Thought so... even tho, when using as a CLI SDK, its fundamental not to rely solely on AGENTS.md
claude has a --append-prompt
i forked for experimenting, and got a example PR here.
https://github.com/openai/codex/pull/4436
that works on top of AGENTS.md
The existing system prompt is so wasteful both in how it prompts and in how it results in an essay after every turn, I really wish y'all would let us change it with a subscription
That would be great if I could actually afford to pay for that