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

Summary

  • Overriding the GPT-5 / GPT-5-Codex system prompt via experimental_instructions_file triggers the Responses API to return 400 {"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

  1. 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.

  1. 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

  1. 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).
  2. 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.

View original on GitHub ↗

This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗