How to use output schema in Codex

Using an output schema makes Codex return a final response that matches a defined JSON object instead of free-form text. That is useful for scripts, CI jobs, and other automation that need stable keys from codex exec.

The --output-schema option points Codex at a JSON Schema file that describes the final assistant message. The final message printed to stdout and the optional file written by -o both follow that schema, while --json remains the separate mode for full JSONL event streaming.

A loose schema can still allow missing or extra fields, so keep required keys explicit and set "additionalProperties": false when the downstream consumer expects a fixed shape. Run the command from a trusted repository directory for the normal path, and use repository-check bypass flags only when the working directory policy blocks the run.

1. Create a JSON Schema file that defines the exact fields the final response must contain.

   schema.json

   {
     "type": "object",
     "properties": {
       "status": {
         "type": "string",
         "enum": ["ok", "action_required"]
       },
       "summary": {
         "type": "string"
       }
     },
     "required": ["status", "summary"],
     "additionalProperties": false
   }

   The schema is passed by file path, so save it before running Codex.

2. Run codex exec with --output-schema and add -o when the same final JSON should also be written to a file.

   $ codex exec --output-schema schema.json -o result.json "Return status ok and summary schema verified."
   {"status":"ok","summary":"schema verified"}

   Codex prints the final JSON to stdout and writes the same final message to result.json when -o is present. Related: How to save the last Codex response to a file

   If Codex stops with a trusted-directory or repository-check error, use How to fix Codex trusted directory error or How to skip Codex git repository checks for that separate policy issue.

3. Open the saved file and confirm it contains the same schema-shaped JSON object.

   $ cat result.json
   {"status":"ok","summary":"schema verified"}

   That file is the clean handoff point for another script, CI step, or parser that expects stable keys instead of free-form text.