@quantumclaw/quantumclaw 2026.3.22

package/docs/providers/kilocode.md

@@ -0,0 +1,74 @@
+---
+title: "Kilo Gateway"
+summary: "Use Kilo Gateway's unified API to access many models in QuantumClaw"
+read_when:
+  - You want a single API key for many LLMs
+  - You want to run models via Kilo Gateway in QuantumClaw
+---
+
+# Kilo Gateway
+
+Kilo Gateway provides a **unified API** that routes requests to many models behind a single
+endpoint and API key. It is OpenAI-compatible, so most OpenAI SDKs work by switching the base URL.
+
+## Getting an API key
+
+1. Go to [app.kilo.ai](https://app.kilo.ai)
+2. Sign in or create an account
+3. Navigate to API Keys and generate a new key
+
+## CLI setup
+
+```bash
+quantumclaw onboard --kilocode-api-key <key>
+```
+
+Or set the environment variable:
+
+```bash
+export KILOCODE_API_KEY="<your-kilocode-api-key>" # pragma: allowlist secret
+```
+
+## Config snippet
+
+```json5
+{
+  env: { KILOCODE_API_KEY: "<your-kilocode-api-key>" }, // pragma: allowlist secret
+  agents: {
+    defaults: {
+      model: { primary: "kilocode/kilo/auto" },
+    },
+  },
+}
+```
+
+## Default model
+
+The default model is `kilocode/kilo/auto`, a smart routing model that automatically selects
+the best underlying model based on the task:
+
+- Planning, debugging, and orchestration tasks route to Claude Opus
+- Code writing and exploration tasks route to Claude Sonnet
+
+## Available models
+
+QuantumClaw dynamically discovers available models from the Kilo Gateway at startup. Use
+`/models kilocode` to see the full list of models available with your account.
+
+Any model available on the gateway can be used with the `kilocode/` prefix:
+
+```
+kilocode/kilo/auto              (default - smart routing)
+kilocode/anthropic/claude-sonnet-4
+kilocode/openai/gpt-5.2
+kilocode/google/gemini-3-pro-preview
+...and many more
+```
+
+## Notes
+
+- Model refs are `kilocode/<model-id>` (e.g., `kilocode/anthropic/claude-sonnet-4`).
+- Default model: `kilocode/kilo/auto`
+- Base URL: `https://api.kilo.ai/api/gateway/`
+- For more model/provider options, see [/concepts/model-providers](/concepts/model-providers).
+- Kilo Gateway uses a Bearer token with your API key under the hood.

package/docs/providers/litellm.md

@@ -0,0 +1,154 @@
+---
+title: "LiteLLM"
+summary: "Run QuantumClaw through LiteLLM Proxy for unified model access and cost tracking"
+read_when:
+  - You want to route QuantumClaw through a LiteLLM proxy
+  - You need cost tracking, logging, or model routing through LiteLLM
+---
+
+# LiteLLM
+
+[LiteLLM](https://litellm.ai) is an open-source LLM gateway that provides a unified API to 100+ model providers. Route QuantumClaw through LiteLLM to get centralized cost tracking, logging, and the flexibility to switch backends without changing your QuantumClaw config.
+
+## Why use LiteLLM with QuantumClaw?
+
+- **Cost tracking** — See exactly what QuantumClaw spends across all models
+- **Model routing** — Switch between Claude, GPT-4, Gemini, Bedrock without config changes
+- **Virtual keys** — Create keys with spend limits for QuantumClaw
+- **Logging** — Full request/response logs for debugging
+- **Fallbacks** — Automatic failover if your primary provider is down
+
+## Quick start
+
+### Via onboarding
+
+```bash
+quantumclaw onboard --auth-choice litellm-api-key
+```
+
+### Manual setup
+
+1. Start LiteLLM Proxy:
+
+```bash
+pip install 'litellm[proxy]'
+litellm --model claude-opus-4-6
+```
+
+2. Point QuantumClaw to LiteLLM:
+
+```bash
+export LITELLM_API_KEY="your-litellm-key"
+
+quantumclaw
+```
+
+That's it. QuantumClaw now routes through LiteLLM.
+
+## Configuration
+
+### Environment variables
+
+```bash
+export LITELLM_API_KEY="sk-litellm-key"
+```
+
+### Config file
+
+```json5
+{
+  models: {
+    providers: {
+      litellm: {
+        baseUrl: "http://localhost:4000",
+        apiKey: "${LITELLM_API_KEY}",
+        api: "openai-completions",
+        models: [
+          {
+            id: "claude-opus-4-6",
+            name: "Claude Opus 4.6",
+            reasoning: true,
+            input: ["text", "image"],
+            contextWindow: 200000,
+            maxTokens: 64000,
+          },
+          {
+            id: "gpt-4o",
+            name: "GPT-4o",
+            reasoning: false,
+            input: ["text", "image"],
+            contextWindow: 128000,
+            maxTokens: 8192,
+          },
+        ],
+      },
+    },
+  },
+  agents: {
+    defaults: {
+      model: { primary: "litellm/claude-opus-4-6" },
+    },
+  },
+}
+```
+
+## Virtual keys
+
+Create a dedicated key for QuantumClaw with spend limits:
+
+```bash
+curl -X POST "http://localhost:4000/key/generate" \
+  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "key_alias": "quantumclaw",
+    "max_budget": 50.00,
+    "budget_duration": "monthly"
+  }'
+```
+
+Use the generated key as `LITELLM_API_KEY`.
+
+## Model routing
+
+LiteLLM can route model requests to different backends. Configure in your LiteLLM `config.yaml`:
+
+```yaml
+model_list:
+  - model_name: claude-opus-4-6
+    litellm_params:
+      model: claude-opus-4-6
+      api_key: os.environ/ANTHROPIC_API_KEY
+
+  - model_name: gpt-4o
+    litellm_params:
+      model: gpt-4o
+      api_key: os.environ/OPENAI_API_KEY
+```
+
+QuantumClaw keeps requesting `claude-opus-4-6` — LiteLLM handles the routing.
+
+## Viewing usage
+
+Check LiteLLM's dashboard or API:
+
+```bash
+# Key info
+curl "http://localhost:4000/key/info" \
+  -H "Authorization: Bearer sk-litellm-key"
+
+# Spend logs
+curl "http://localhost:4000/spend/logs" \
+  -H "Authorization: Bearer $LITELLM_MASTER_KEY"
+```
+
+## Notes
+
+- LiteLLM runs on `http://localhost:4000` by default
+- QuantumClaw connects via the OpenAI-compatible `/v1/chat/completions` endpoint
+- All QuantumClaw features work through LiteLLM — no limitations
+
+## See also
+
+- [LiteLLM Docs](https://docs.litellm.ai)
+- [Model Providers](/concepts/model-providers)

package/docs/providers/minimax.md

@@ -0,0 +1,224 @@
+---
+summary: "Use MiniMax models in QuantumClaw"
+read_when:
+  - You want MiniMax models in QuantumClaw
+  - You need MiniMax setup guidance
+title: "MiniMax"
+---
+
+# MiniMax
+
+QuantumClaw's MiniMax provider defaults to **MiniMax M2.7** and keeps
+**MiniMax M2.5** in the catalog for compatibility.
+
+## Model lineup
+
+- `MiniMax-M2.7`: default hosted text model.
+- `MiniMax-M2.7-highspeed`: faster M2.7 text tier.
+- `MiniMax-M2.5`: previous text model, still available in the MiniMax catalog.
+- `MiniMax-M2.5-highspeed`: faster M2.5 text tier.
+- `MiniMax-VL-01`: vision model for text + image inputs.
+
+## Choose a setup
+
+### MiniMax OAuth (Coding Plan) - recommended
+
+**Best for:** quick setup with MiniMax Coding Plan via OAuth, no API key required.
+
+Enable the bundled OAuth plugin and authenticate:
+
+```bash
+quantumclaw plugins enable minimax  # skip if already loaded.
+quantumclaw gateway restart  # restart if gateway is already running
+quantumclaw onboard --auth-choice minimax-portal
+```
+
+You will be prompted to select an endpoint:
+
+- **Global** - International users (`api.minimax.io`)
+- **CN** - Users in China (`api.minimaxi.com`)
+
+See [MiniMax plugin README](https://github.com/quantumclaw/quantumclaw/tree/main/extensions/minimax) for details.
+
+### MiniMax M2.7 (API key)
+
+**Best for:** hosted MiniMax with Anthropic-compatible API.
+
+Configure via CLI:
+
+- Run `quantumclaw configure`
+- Select **Model/auth**
+- Choose a **MiniMax** auth option
+
+```json5
+{
+  env: { MINIMAX_API_KEY: "sk-..." },
+  agents: { defaults: { model: { primary: "minimax/MiniMax-M2.7" } } },
+  models: {
+    mode: "merge",
+    providers: {
+      minimax: {
+        baseUrl: "https://api.minimax.io/anthropic",
+        apiKey: "${MINIMAX_API_KEY}",
+        api: "anthropic-messages",
+        models: [
+          {
+            id: "MiniMax-M2.7",
+            name: "MiniMax M2.7",
+            reasoning: true,
+            input: ["text"],
+            cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0.12 },
+            contextWindow: 200000,
+            maxTokens: 8192,
+          },
+          {
+            id: "MiniMax-M2.7-highspeed",
+            name: "MiniMax M2.7 Highspeed",
+            reasoning: true,
+            input: ["text"],
+            cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0.12 },
+            contextWindow: 200000,
+            maxTokens: 8192,
+          },
+          {
+            id: "MiniMax-M2.5",
+            name: "MiniMax M2.5",
+            reasoning: true,
+            input: ["text"],
+            cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0.12 },
+            contextWindow: 200000,
+            maxTokens: 8192,
+          },
+          {
+            id: "MiniMax-M2.5-highspeed",
+            name: "MiniMax M2.5 Highspeed",
+            reasoning: true,
+            input: ["text"],
+            cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0.12 },
+            contextWindow: 200000,
+            maxTokens: 8192,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+### MiniMax M2.7 as fallback (example)
+
+**Best for:** keep your strongest latest-generation model as primary, fail over to MiniMax M2.7.
+Example below uses Opus as a concrete primary; swap to your preferred latest-gen primary model.
+
+```json5
+{
+  env: { MINIMAX_API_KEY: "sk-..." },
+  agents: {
+    defaults: {
+      models: {
+        "anthropic/claude-opus-4-6": { alias: "primary" },
+        "minimax/MiniMax-M2.7": { alias: "minimax" },
+      },
+      model: {
+        primary: "anthropic/claude-opus-4-6",
+        fallbacks: ["minimax/MiniMax-M2.7"],
+      },
+    },
+  },
+}
+```
+
+### Optional: Local via LM Studio (manual)
+
+**Best for:** local inference with LM Studio.
+We have seen strong results with MiniMax M2.5 on powerful hardware (e.g. a
+desktop/server) using LM Studio's local server.
+
+Configure manually via `quantumclaw.json`:
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "lmstudio/minimax-m2.5-gs32" },
+      models: { "lmstudio/minimax-m2.5-gs32": { alias: "Minimax" } },
+    },
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      lmstudio: {
+        baseUrl: "http://127.0.0.1:1234/v1",
+        apiKey: "lmstudio",
+        api: "openai-responses",
+        models: [
+          {
+            id: "minimax-m2.5-gs32",
+            name: "MiniMax M2.5 GS32",
+            reasoning: true,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 196608,
+            maxTokens: 8192,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+## Configure via `quantumclaw configure`
+
+Use the interactive config wizard to set MiniMax without editing JSON:
+
+1. Run `quantumclaw configure`.
+2. Select **Model/auth**.
+3. Choose a **MiniMax** auth option.
+4. Pick your default model when prompted.
+
+## Configuration options
+
+- `models.providers.minimax.baseUrl`: prefer `https://api.minimax.io/anthropic` (Anthropic-compatible); `https://api.minimax.io/v1` is optional for OpenAI-compatible payloads.
+- `models.providers.minimax.api`: prefer `anthropic-messages`; `openai-completions` is optional for OpenAI-compatible payloads.
+- `models.providers.minimax.apiKey`: MiniMax API key (`MINIMAX_API_KEY`).
+- `models.providers.minimax.models`: define `id`, `name`, `reasoning`, `contextWindow`, `maxTokens`, `cost`.
+- `agents.defaults.models`: alias models you want in the allowlist.
+- `models.mode`: keep `merge` if you want to add MiniMax alongside built-ins.
+
+## Notes
+
+- Model refs are `minimax/<model>`.
+- Default text model: `MiniMax-M2.7`.
+- Alternate text models: `MiniMax-M2.7-highspeed`, `MiniMax-M2.5`, `MiniMax-M2.5-highspeed`.
+- Coding Plan usage API: `https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains` (requires a coding plan key).
+- Update pricing values in `models.json` if you need exact cost tracking.
+- Referral link for MiniMax Coding Plan (10% off): [https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link)
+- See [/concepts/model-providers](/concepts/model-providers) for provider rules.
+- Use `quantumclaw models list` and `quantumclaw models set minimax/MiniMax-M2.7` to switch.
+
+## Troubleshooting
+
+### "Unknown model: minimax/MiniMax-M2.7"
+
+This usually means the **MiniMax provider isn’t configured** (no provider entry
+and no MiniMax auth profile/env key found). A fix for this detection is in
+**2026.1.12** (unreleased at the time of writing). Fix by:
+
+- Upgrading to **2026.1.12** (or run from source `main`), then restarting the gateway.
+- Running `quantumclaw configure` and selecting a **MiniMax** auth option, or
+- Adding the `models.providers.minimax` block manually, or
+- Setting `MINIMAX_API_KEY` (or a MiniMax auth profile) so the provider can be injected.
+
+Make sure the model id is **case‑sensitive**:
+
+- `minimax/MiniMax-M2.7`
+- `minimax/MiniMax-M2.7-highspeed`
+- `minimax/MiniMax-M2.5`
+- `minimax/MiniMax-M2.5-highspeed`
+
+Then recheck with:
+
+```bash
+quantumclaw models list
+```

package/docs/providers/mistral.md

@@ -0,0 +1,54 @@
+---
+summary: "Use Mistral models and Voxtral transcription with QuantumClaw"
+read_when:
+  - You want to use Mistral models in QuantumClaw
+  - You need Mistral API key onboarding and model refs
+title: "Mistral"
+---
+
+# Mistral
+
+QuantumClaw supports Mistral for both text/image model routing (`mistral/...`) and
+audio transcription via Voxtral in media understanding.
+Mistral can also be used for memory embeddings (`memorySearch.provider = "mistral"`).
+
+## CLI setup
+
+```bash
+quantumclaw onboard --auth-choice mistral-api-key
+# or non-interactive
+quantumclaw onboard --mistral-api-key "$MISTRAL_API_KEY"
+```
+
+## Config snippet (LLM provider)
+
+```json5
+{
+  env: { MISTRAL_API_KEY: "sk-..." },
+  agents: { defaults: { model: { primary: "mistral/mistral-large-latest" } } },
+}
+```
+
+## Config snippet (audio transcription with Voxtral)
+
+```json5
+{
+  tools: {
+    media: {
+      audio: {
+        enabled: true,
+        models: [{ provider: "mistral", model: "voxtral-mini-latest" }],
+      },
+    },
+  },
+}
+```
+
+## Notes
+
+- Mistral auth uses `MISTRAL_API_KEY`.
+- Provider base URL defaults to `https://api.mistral.ai/v1`.
+- Onboarding default model is `mistral/mistral-large-latest`.
+- Media-understanding default audio model for Mistral is `voxtral-mini-latest`.
+- Media transcription path uses `/v1/audio/transcriptions`.
+- Memory embeddings path uses `/v1/embeddings` (default model: `mistral-embed`).

package/docs/providers/models.md

@@ -0,0 +1,45 @@
+---
+summary: "Model providers (LLMs) supported by QuantumClaw"
+read_when:
+  - You want to choose a model provider
+  - You want quick setup examples for LLM auth + model selection
+title: "Model Provider Quickstart"
+---
+
+# Model Providers
+
+QuantumClaw can use many LLM providers. Pick one, authenticate, then set the default
+model as `provider/model`.
+
+## Quick start (two steps)
+
+1. Authenticate with the provider (usually via `quantumclaw onboard`).
+2. Set the default model:
+
+```json5
+{
+  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
+}
+```
+
+## Supported providers (starter set)
+
+- [OpenAI (API + Codex)](/providers/openai)
+- [Anthropic (API + Claude Code CLI)](/providers/anthropic)
+- [OpenRouter](/providers/openrouter)
+- [Vercel AI Gateway](/providers/vercel-ai-gateway)
+- [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
+- [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot)
+- [Mistral](/providers/mistral)
+- [Synthetic](/providers/synthetic)
+- [OpenCode (Zen + Go)](/providers/opencode)
+- [Z.AI](/providers/zai)
+- [GLM models](/providers/glm)
+- [MiniMax](/providers/minimax)
+- [Venice (Venice AI)](/providers/venice)
+- [Amazon Bedrock](/providers/bedrock)
+- [Qianfan](/providers/qianfan)
+- [xAI](/providers/xai)
+
+For the full provider catalog (xAI, Groq, Mistral, etc.) and advanced configuration,
+see [Model providers](/concepts/model-providers).

package/docs/providers/modelstudio.md

@@ -0,0 +1,66 @@
+---
+title: "Model Studio"
+summary: "Alibaba Cloud Model Studio setup (Coding Plan, dual region endpoints)"
+read_when:
+  - You want to use Alibaba Cloud Model Studio with QuantumClaw
+  - You need the API key env var for Model Studio
+---
+
+# Model Studio (Alibaba Cloud)
+
+The Model Studio provider gives access to Alibaba Cloud Coding Plan models,
+including Qwen and third-party models hosted on the platform.
+
+- Provider: `modelstudio`
+- Auth: `MODELSTUDIO_API_KEY`
+- API: OpenAI-compatible
+
+## Quick start
+
+1. Set the API key:
+
+```bash
+quantumclaw onboard --auth-choice modelstudio-api-key
+```
+
+2. Set a default model:
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "modelstudio/qwen3.5-plus" },
+    },
+  },
+}
+```
+
+## Region endpoints
+
+Model Studio has two endpoints based on region:
+
+| Region     | Endpoint                             |
+| ---------- | ------------------------------------ |
+| China (CN) | `coding.dashscope.aliyuncs.com`      |
+| Global     | `coding-intl.dashscope.aliyuncs.com` |
+
+The provider auto-selects based on the auth choice (`modelstudio-api-key` for
+global, `modelstudio-api-key-cn` for China). You can override with a custom
+`baseUrl` in config.
+
+## Available models
+
+- **qwen3.5-plus** (default) - Qwen 3.5 Plus
+- **qwen3-max** - Qwen 3 Max
+- **qwen3-coder** series - Qwen coding models
+- **GLM-5**, **GLM-4.7** - GLM models via Alibaba
+- **Kimi K2.5** - Moonshot AI via Alibaba
+- **MiniMax-M2.5** - MiniMax via Alibaba
+
+Most models support image input. Context windows range from 200K to 1M tokens.
+
+## Environment note
+
+If the Gateway runs as a daemon (launchd/systemd), make sure
+`MODELSTUDIO_API_KEY` is available to that process (for example, in
+`~/.quantumclaw/.env` or via `env.shellEnv`).