Browse documentation

Technical documentation / Reference

Provider authentication

Feature docs index · Repository README

Connect a provider

Run /login in Mission Control. Choose OpenAI Codex for ChatGPT OAuth, Claude Subscription for CLI-managed claude.ai access, Anthropic for Messages API access billed through Anthropic API credits, OpenAI for API-key access, or Custom Provider for an OpenAI-compatible service.

Never commit credentials, copied tokens, account ids, terminal auth output, or transcripts containing secrets. Settings contain non-secret options only; credentials belong in the provider's environment variable or private auth.json under ~/.magi-code (or $MC_HOME).

OpenAI Codex

/login openai-codex

Complete the ChatGPT browser OAuth flow, then check access:

magi-code --provider openai-codex --model gpt-5.5 --prompt "Reply with only: ok"

openai-codex requires provider-keyed OAuth credentials and a ChatGPT account id. It calls https://chatgpt.com/backend-api/codex/responses. Inference and model discovery do not use --api-key, MC_API_KEY, OPENAI_API_KEY, or custom-provider keys. Do not pass OAuth tokens through those options: runtime-token/API-key auth is refused for Codex.

Login displays an authorization URL and binds 127.0.0.1:1455 for the registered redirect URI http://localhost:1455/auth/callback. Credentials are saved in auth.json. The visible URL is transient and redacted from logs/debug output. Manual redirect/code input is visually redacted, never stored in settings or sessions or sent to the model, and goes to the token exchange only when explicitly submitted.

At 80×24, custom setup shows the active field; Tab and Shift-Tab move between fields. OAuth keeps browser, copy, and redirect-input controls visible. URLs that exceed the available space show a page count: Page Up and Page Down cycle through every URL page. Copy URL always copies the complete URL.

/logout openai-codex

Logout removes the local OAuth record only. It does not revoke remote tokens or sign out browser sessions.

OpenAI API

Export OPENAI_API_KEY before launching magi-code, then choose OpenAI in /login or run /login openai. Review the prefilled custom-provider form and press Enter to save:

This uses the existing custom-provider Responses transport, not ChatGPT OAuth. Setup stores only metadata and asks before replacing an existing openai configuration. Refresh the catalog in Settings → Choose models → Available models, then select /model openai/<model-name>. /logout openai removes the custom-provider configuration; it does not unset the environment variable.

Anthropic

export ANTHROPIC_API_KEY="<ANTHROPIC_API_KEY>"
magi-code --provider anthropic --model claude-sonnet-4-5-20250929 --prompt "Reply with only: ok"

Auth checks ANTHROPIC_API_KEY first, then the provider-keyed anthropic API-key record in auth.json. OAuth and no-auth configurations are rejected. Anthropic ignores --api-key, MC_API_KEY, and OpenAI keys such as OPENAI_API_KEY.

To save the model selection without storing a key:

{
  "agent": { "model": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-5-20250929"
  }
  } }

Use Settings → Choose models → Available models → Refresh catalog, then /model anthropic/<model-name> to select a cached model. Missing Anthropic auth does not block Codex or custom-provider catalogs. /logout anthropic removes only the local API-key record; it cannot unset or override ANTHROPIC_API_KEY.

Anthropic API retries only before text, reasoning, tool, usage or completion progress. HTTP 429/529 and stream rate_limit_error/overloaded_error allow four total attempts, waiting 2/10/20 seconds; HTTP 408, 425, 500, 502, 503, 504 and stream api_error allow three total attempts, waiting approximately 250/750 milliseconds (±20%). Other stream error types do not retry. Message-start usage counts as progress. Valid retry-after-ms or retry-after (seconds or HTTP-date) replaces a scheduled wait; milliseconds take precedence, invalid values use the schedule, and waits above 60 seconds fail immediately. All waits remain cancellable. Shared behavior, including OpenAI/Codex/compatible endpoints and the separate incomplete-response continuation: automatic retries. Claude Subscription admission is unchanged.

Prompt caching

Anthropic API prompt caching defaults to one hour. Override providers.anthropic.cache_ttl in settings.json:

{
  "providers": {
    "anthropic": { "cache_ttl": "1h" }
  }
}

Use "5m" for a shorter cache lifetime, or null to disable cache control. Magi-code sends top-level cache_control, which moves the cache breakpoint forward as the conversation grows. Cache hits require a matching prefix, enough cacheable tokens for the model, and an unexpired entry. Cache writes cost extra; enabling caching does not guarantee savings. Claude subscription leaves caching to the Claude CLI and does not use this setting.

The TUI's session input total includes uncached input, cache reads, and cache writes. Its cache percentage measures cache reads divided by that total, not tokens written to cache or money saved. A first request can write the cache while showing 0% reads. Later output-only usage updates retain earlier input and cache counts.

Claude subscription

This provider uses your claude.ai subscription through installed Claude Code. It needs no separate Agent SDK package or Anthropic API key. The separate anthropic provider still requires an API key.

Install Claude Code, then choose either authentication method:

Opus 5.5 needs Claude Code 2.1.280 or newer. Select /model claude-subscription/claude-opus-5-5, or launch with --provider claude-subscription --model claude-opus-5-5. Readiness accepts a successful claude auth status --json with loggedIn: true and authMethod: "claude.ai" or "oauth_token".

The CLI chooses the credential for both readiness checks and requests. When both methods are available, CLAUDE_CODE_OAUTH_TOKEN takes precedence. Magi-code inherits the variable without reading, logging, or storing its value. Setup-token logins have no account metadata for a direct quota lookup. Instead, quota comes from the rate-limit headers on each completed request, and the usage display reports usage unavailable until the first request finishes.

Magi-code never installs dependencies, copies OAuth tokens, or uses --bare. To stop using a setup token, unset CLAUDE_CODE_OAUTH_TOKEN before launching magi-code. To remove a stored login, run claude auth logout.

Readiness checks and requests remove ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_FOUNDRY_API_KEY, and the CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, and CLAUDE_CODE_USE_FOUNDRY backend selectors from the Claude child environment. The parent environment stays unchanged, so Anthropic API and Claude subscription models can be enabled together without sending an API key through the subscription provider.

Model catalog

Refreshing the catalog lists Anthropic models from models.dev, using their names and metadata. These are candidates. They aren't confirmed for your account, and the CLI and your plan decide what you can actually use. API token prices are left out. If a models.dev refresh fails and the CLI is ready, magi-code keeps showing the cached candidates. Loading from cache alone never runs the CLI or touches the network, but sending a request still requires a ready CLI.

Claude subscription normally uses a 202,000-token input ceiling. Explicit [1m] selections for Opus 4.6 and newer, Fable 5 and newer, Sonnet 5.5 and newer and Haiku 5.5 and newer use 1,000,000 tokens, including claude-opus-5-5[1m] and claude-fable-5[1m]. Refresh the catalog to show extended-context variants of eligible listed models. Account access and CLI support still determine acceptance; this ceiling is not evidence of successful full-window use for every model. No model is switched automatically. Model overrides can lower, not raise, these ceilings. Compaction uses the shared agent.compaction.auto settings and inherits the active model; no alternative provider is required. See context limits.

Execution, cost, and limits

Magi-code owns tools, approvals, session history, and compaction. Each request starts the installed CLI and a temporary relay that permits one generation. The CLI supplies authentication but cannot execute host tools. This requires Unix; on Windows, run magi-code and Claude Code inside WSL.

Text, reasoning, and partial usage stream as they arrive. Tools run only after the complete response and CLI result pass validation. A failed or incomplete response keeps accepted partial text but releases no incomplete tool calls. There is no automatic retry through another model or API-key billing.

Non-default reasoning levels map to the CLI's --effort option. The CLI controls output limits. Magi-code applies shared streaming timeouts and context budgeting; see Claude subscription for the execution contract.

Subscription extra-usage credits may still be charged by Claude Code. Magi-code does not enable credits or change billing settings. Check your account before using extended context.

Custom OpenAI-compatible providers

Use /login custom-provider to enter a label, API-root base URL, and optional API-key environment-variable name. Setup saves non-secret metadata, never a key value. Provider ids use lowercase slugs such as local-provider; openai-codex is reserved. An id such as openai can use the custom-provider workflow.

If you configure an API-key variable, only that named variable is read and it must be non-empty for the provider to be ready. Without one, you can use a no-auth local provider:

# No-auth local provider:
magi-code --provider local-provider --model model-name --prompt "Reply with only: ok"

# Env-var-backed provider:
export HOSTED_PROVIDER_API_KEY="<CUSTOM_PROVIDER_API_KEY>"
magi-code --provider hosted-provider --model model-name --prompt "Reply with only: ok"

Custom requests use {base_url}/responses by default. The URL is a normalized API root, not a request endpoint. Model discovery uses {base_url}/models. Edit providers.custom.<id> in settings.json for options not prompted by login:

OptionBehavior
use_responses_endpoint: falseOpts out of the default Responses endpoint and uses {base_url}/chat/completions; discovery stays on /models. There is no automatic endpoint detection. Codex is unaffected.
supports_text_verbosity: trueDeclares Responses text.verbosity support; defaults false. Emission also requires Responses mode and shared providers.openai_responses.text_verbosity.
fast_modeExplicit service tier and exact model ids, or sole "*" entry. No capability inference from names. See Fast mode.
extra_modelsAdds provider-local model ids omitted by /models; dedupes against discovered ids and does not change the endpoint.
models_dev_providerExact models.dev namespace for matching context/reasoning/output-token metadata, not auth. Defaults to the provider id.

For a Z.ai Coding Plan model omitted by /models:

{
  "providers": { "custom": {
    "zai": {
      "label": "Z.ai",
      "base_url": "https://api.z.ai/api/coding/paas/v4",
      "api_key_env_var": "ZAI_API_KEY",
      "extra_models": ["glm-5.2"]
    }
  }
  } }

Use glm-5.2, not zai/glm-5.2, in extra_models. Catalog enrichment requires an exact namespace and model id match, never a label, host, prefix, or base-URL guess. For example, id openai uses namespace openai; id custom-openai needs models_dev_provider: "openai" to use that metadata. An explicit namespace always wins.

/logout <custom-provider-id> removes custom-provider metadata only from global settings. Project provider definitions and environment credentials remain, as do sessions, unrelated settings, and other providers.

Mission Control login controls

/login opens the staged Connect Provider modal with provider status. Use Up/Down and Enter to choose.

Cancelling before Saving preserves existing credentials and settings. Once durable custom-provider saving begins, it cannot be cancelled; the modal stays open until completion is reconciled.

Fast mode

Use /fast on or set global agent.fast.enabled: true with agent.fast.ultrafast: false. It defaults off, ignores project overrides, and applies to eligible primary turns, subagents, and manual or automatic blocking compaction, not session titles. /ultrafast on sets both flags true; either command's off clears both. Only one speed mode is active at a time.

Codex selects the exact catalog-advertised Fast tier id, matching Fast display/name case-insensitively. Explicit tier metadata without Fast keeps the request Standard. Legacy additional_speed_tiers maps fast to the Codex wire tier priority. When tier metadata or the catalog entry is missing, strictly normalized Codex GPT versions >=5.4 use the priority fallback. Unsupported models/providers request no Fast tier.

Codex OAuth Responses requests include a Codex-only x-codex-routing-hint: model=<normalized-model>, even with Fast off, unless it is invalid as an HTTP header value. With a selected Fast tier, it adds ;tier=<service-tier-id> and the body includes the exact service_tier. The hint is not sent to catalogs or custom providers.

Custom providers require explicit providers.custom.<id>.fast_mode, for example {"service_tier":"priority","models":["model-name"]}. The tier is trimmed; model ids are preserved exactly. Ids must contain 1 to 200 Unicode characters without whitespace, control characters, or secret-like values. "*" must be the sole entry. See Configuration for schema validation rules.

Fast is not an entitlement check or speed guarantee. The provider controls access, routing, speed, and billing/credits. In ChatGPT-authenticated Codex, Fast routing happens server-side and final response tiers do not reliably identify it: default, auto, or an absent tier leaves Fast unconfirmed, not downgraded. These observations produce no warning; /fast status explains the limitation without claiming Fast was confirmed. Custom-provider tier mismatches and missing confirmations still produce warnings. See OpenAI's explanation.

Ultrafast is a separate tier selected by /ultrafast, not /fast. For Codex, the selected model's cached catalog must advertise exact tier id ultrafast; there is no model-name inference, model switch, or automatic Fast fallback. Without support metadata, requests remain Standard and status reports Ultrafast unavailable. Codex speed guidance lists Ultrafast for GPT-6 Astra on eligible plans/workspaces; GPT-6.1 Sol supports Standard and Fast. Catalog support is not an entitlement guarantee: the backend may reject access. Ultrafast has higher usage charges; it is never enabled automatically. Custom providers can explicitly configure service_tier: "ultrafast" through their existing fast_mode metadata and /fast; /ultrafast itself is Codex-only.

Response detail

providers.openai_responses.text_verbosity accepts low, medium, or high. Codex uses it directly. Custom Responses providers require this value plus use_responses_endpoint: true and supports_text_verbosity: true; otherwise they omit the field.

Verbosity affects visible detail, output size, latency, and cost. It does not control reasoning effort, expose hidden/encrypted reasoning, control tool calls, or impose a hard output-token limit or exact answer length.

Credential storage and refresh

auth.json is private and owner-only on Unix. Login and logout preserve other providers' records. Do not edit internal revision or provider_generations metadata.

Codex refreshes near-expired or expired credentials when a refresh token is available. Refreshes also cover auxiliary work such as model discovery. Network requests run outside storage locks; stale responses cannot overwrite newer credentials or restore a logged-out record.

See Configuration for file limits, paths, and credential boundaries.

Edit this page on GitHub ↗