Choose a provider

Connect a model provider and assign models to q's native roles.

View Markdown

Supported providers

q’s managed Gateway supports:

OpenAI-compatible HTTP APIs, including local servers
OpenRouter
xAI and Grok
Anthropic’s native Messages API
the local Codex App Server using the current Codex login

Configure the Gateway

Open Settings → Providers in Studio to add providers, then use Settings → Services for listener settings. The Studio host supervises its managed Gateway child on a private loopback port.

Provider changes are activated by starting a replacement first. If the replacement cannot start, q keeps the currently running configuration instead of switching to a broken one.

Use environment-variable references for provider credentials whenever possible. Global provider definitions live in ~/.q/providers.json.

For providers with API type openrouter, Q sends HTTP-Referer: https://q.saturday.ne.kr and X-OpenRouter-Title: Q to OpenRouter. OpenRouter may include attributed usage in its public app rankings. To use your own app identity, set either header in that provider’s headers object in ~/.q/providers.json; configured values take precedence over Q’s defaults.

Assign model roles

Open Settings → Models to assign a model to the main chat and specialized roles such as interviewer, manager, research, reviewer, coder, commit, thinker, and librarian. The senior developer uses reviewer; the junior developer uses coder.

Create a reusable custom role from the role assignment list. Custom subagents can select that role while keeping their own tools and delegation grants.

Workspace overrides are stored in .q/model.json; global assignments remain in ~/.q/config.yaml.

Choose a model API

q can call Chat Completions or Responses for each concrete model. Known native OpenAI, xAI, and OpenRouter Gateway routes prefer Responses. Codex App Server, Anthropic native, and unknown compatible routes keep their existing API. The Gateway continues accepting both incoming routes.

The Codex App Server runs q’s minimal agent with inherited private MCP tools, including node_repl, disabled. Q’s own tools remain available and visible in its session trace.

Use the model API controls in Studio or set model_api_modes in ~/.q/config.yaml to override a model:

yaml

model_api_modes:
  openai/gpt-5: responses
  local/example: chat_completions

The override key is the full model ID. A default model group with multiple candidates cannot use Responses; role-specific groups select the API for each concrete candidate. Saved sessions use a common message format across both API choices.

Configure embeddings

The model assignment screen also has a global embedding target. Select an embedding-capable model and enter the vector dimensions expected by that model. q accepts dimensions from 1 through 4096.

Embedding configuration is global because Workspace Memory and the Library maintain shared derived indexes. It cannot be overridden per workspace. Assigning or changing the model reconfigures the rebuildable HNSW projections and backfills active Agent Skills for the new model. Clearing the target leaves skill and history retrieval on BM25 only.

The configured provider must support embedding requests, and the dimensions must match the selected model. An embedding setup error is reported without making the underlying JSON records unavailable.

Fallback groups

A role may reference an ordered model group. q tries the next candidate after a timeout or transient HTTP 5xx response.

User cancellation, tool failure, and validation errors do not trigger fallback. Those outcomes need a changed request, tool state, or configuration rather than a different model endpoint.