Stravia Docs

Codex

Codex CLI integrates with Stravia through the open-responses protocol. Desktop can write configuration to your Codex directory; the adapter generates config.toml and a model catalog JSON file.

Prerequisites

Connect an upstream Model Service, create an enabled Stravia Model ID with an enabled destination, and create an enabled API Key that allows the Model ID. Choose Codex only after the Stravia model is callable.

Configuration

Protocol: open-responses
Configuration location: ~/.codex/config.toml and ~/.codex/stravia-models.json (Desktop Apply) or manual
Required settings:

  • model_provider: Set to stravia
  • model_catalog_json: Path to the generated Stravia model catalog
  • model_providers.stravia.base_url: Server address (e.g., http://127.0.0.1:23471/v1)
  • model_providers.stravia.experimental_bearer_token: Your Stravia API Key

Apply configuration (Desktop only)

From Connect clients, select Codex, choose your API Key and models, then click Apply to Client. Desktop writes both the updated config.toml and a stravia-models.json catalog to your Codex directory.

Manual configuration

Edit ~/.codex/config.toml and add the Stravia provider:

model_provider = "stravia"
model_catalog_json = "~/.codex/stravia-models.json"

[model_providers.stravia]
name = "Stravia Gateway"
base_url = "http://127.0.0.1:23471/v1"
wire_api = "responses"
experimental_bearer_token = "<your-api-key>"
toml

Then create ~/.codex/stravia-models.json with the catalog from the Preview section in Stravia Connect. Copy the entire second preview block (JSON catalog), which includes all model metadata required by Codex.

Verify the connection

After configuration, use Codex to make a request. Check Request history in Stravia to confirm the request arrived and the model responded.

Troubleshoot a failed request

Check that model_catalog_json points to the generated catalog, base_url targets Stravia's /v1 endpoint, and the bearer token is the Stravia API Key. Confirm the catalog entry's slug is the Model ID allowed by that key. If no request appears in Request history, check the URL and client network path; otherwise inspect the recorded error. Writing the two files is not proof that Codex connected.

Next steps

For other clients see Other clients . For general client configuration see Connect clients .