How to use an output schema in Codex

Automation that reads Codex output needs one predictable final object, not a paragraph whose wording changes between runs. Passing a JSON Schema to codex exec narrows the final assistant message to named keys that a script, CI step, or release checklist can parse without guessing.

The --output-schema option reads a schema file from disk and applies it to the final assistant response. --output-last-message writes that final response to a file, while stdout still shows the same final message unless --json is used for the separate JSONL event stream.

The schema should describe the object another program actually expects. Mark required fields explicitly, use enums for closed status values, and set "additionalProperties": false when extra keys would break the consumer. Run the command from an authenticated, trusted repository directory, because repository trust and API authentication are checked before Codex can return schema-shaped output.

1. Create a JSON Schema file with the final keys automation expects.

   schema.json

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

   The file path is passed to --output-schema, so keep it next to the script or job that launches Codex.
   Tool: JSON Schema Generator

2. Run codex exec with the schema file and a saved-output path.

   $ codex exec --output-schema schema.json --output-last-message result.json "Return status ok, summary schema verified, next_action none."
   {"status":"ok","summary":"schema verified","next_action":"none"}

   The final schema-shaped message prints to stdout and is also written to result.json. If a trusted-directory error appears first, fix the launch directory before retrying.
   Related: How to fix the Codex trusted-directory error

3. Open the saved JSON file.

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

4. Check the final object before handing it to another script.

   $ jq -e '.status == "ok" and .next_action == "none"' result.json
   true

   Use --json only when the consumer needs every Codex event as JSONL instead of one final JSON object.
   Related: How to enable JSON output in Codex