Codex CLI

Add Summa as a Codex model provider over the OpenAI Responses protocol — single models, debate, and custom panels, all in your terminal.

Connect Codex to Summa

Codex talks to Summa through its OpenAI-compatible Responses endpoint. Add a provider block to ~/.codex/config.toml, export your key, and launch. Create a key on the API Keys page first.

model = "summa-fast"
model_provider = "summa"

[model_providers.summa]
name = "Summa"
base_url = "https://alpha.backend.summachat.com/api/v1"
env_key = "SUMMA_API_KEY"
wire_api = "responses"

export SUMMA_API_KEY="YOUR_API_KEY"
codex

wire_api = "responses" is required — Summa serves Codex over the OpenAI Responses protocol at https://alpha.backend.summachat.com/api/v1/responses.
env_key names the environment variable Codex reads the key from; keep the actual key out of the file.
Auth is a bearer token under the hood: Authorization: Bearer <API_KEY>. Codex handles that for you once SUMMA_API_KEY is exported.

Single mode — summa-fast

summa-fast is one fast model with full tool support — shell commands and file edits stream live. It is the best default for agentic coding in Codex. With the config above it is already selected, so just launch and prompt.

# model = "summa-fast" is already set in config.toml
codex "add a rate limiter to server.py and run the tests"

Point model at any single catalog model with the summa/<slug> form — for example summa/openai/gpt-5 — and you keep full tool support. The Get models section below shows how to find ids.

Debate mode — summa-debate

Switch the model to summa-debate and a panel of models each answers, then a moderator synthesizes a single response. Debate is slower and pricier than a single model — tools are accepted but not invoked during a debate, so use it for hard reasoning and review, not shell-heavy edits.

model = "summa-debate"
model_provider = "summa"

[model_providers.summa]
name = "Summa"
base_url = "https://alpha.backend.summachat.com/api/v1"
env_key = "SUMMA_API_KEY"
wire_api = "responses"

codex "review this migration plan for data-loss risks"

Prefer a curated panel? Use a preset id: summa-debate-coding (Claude Sonnet 4.5 moderator + GPT-5 + Gemini 2.5 Pro) or summa-debate-reasoning (GPT-5 moderator + Claude Opus 4.1 + Gemini 2.5 Pro).

Switching between modes is just changing the model string — nothing else in your setup changes. In Codex the reliable way is to edit the model line in ~/.codex/config.toml and relaunch:

# swap any of these in — the provider block stays identical
model = "summa-fast"            # fast single model, full tools
# model = "summa/openai/gpt-5"  # a specific catalog model
# model = "summa-debate"        # panel + synthesized answer
# model = "summa-debate-coding" # curated coding panel

If your Codex build supports it, you can override per-run on the CLI with --model summa-debate. Editing config.toml is the reliable path across versions.
Only the model string changes between single and debate modes — the provider block, base URL, and key stay the same.

You'll feel the debate. On a summa-debate request the panel streams a live transcript — a short header, then each model's turn as it finishes, then a ── Synthesized answer ── divider before the moderator's final answer streams token by token. No more staring at a frozen stream while the panel thinks.

Custom panel — the summa block

To pick the exact models on the panel you use the summa request-body block. It overrides the model string and works on /chat/completions, /responses, and /messages.

Codex's config.toml has no per-request body hook, so you cannot attach a custom summa block from the Codex CLI itself. In Codex, use the debate preset ids above. To ship a custom panel, drive Summa from the Python SDK or cURL, where you control the JSON body.

Here is the block those guides send — same Responses endpoint Codex uses, just with a body you control:

{
  "model": "summa-debate",
  "summa": {
  "panel": ["openai/gpt-5", "anthropic/claude-sonnet-4.5"],
  "moderator": "anthropic/claude-sonnet-4.5"
}
}

panel holds 2 to 8 distinct model slugs — the same ids as summa/<slug> but without the summa/ prefix.
moderator is optional and synthesizes the final answer from all panel turns; it must be one of the panel slugs. Omit it and panel[0] — the first slug you list — moderates by default.
The summa block overrides the model string, so the panel is exactly what you list.

In Codex, the debate presets bake in the moderator: summa-debate-coding uses Claude Sonnet 4.5 and summa-debate-reasoning uses GPT-5. To choose a different moderator you need the summa block — see cURL.

Get models

List the catalog with GET /models and drop any returned id into your model line (or, minus the summa/ prefix, into a panel).

curl "https://alpha.backend.summachat.com/api/v1/models?search=gpt&limit=50&offset=0" \
  -H "Authorization: Bearer $SUMMA_API_KEY"

{
  "object": "list",
  "data": [
    { "id": "summa/openai/gpt-5", "display_name": "GPT-5" }
  ],
  "has_more": false
}

Use an id straight from data[]: set model = "summa/openai/gpt-5" in config.toml for a single model, or list openai/gpt-5 (prefix dropped) inside a custom panel.

Errors & billing

401 — missing or invalid key. Re-export SUMMA_API_KEY and check the value on API Keys.
402 — out of API credit. Top up on Credits.
400 — a malformed summa block (panel too small, duplicate slugs, or a moderator not in the panel).
Billing is prepaid: model token cost plus a 30% platform fee. A 3-model debate costs roughly 3x a single model.