@quantumclaw/quantumclaw 2026.3.22

package/docs/providers/openai.md

@@ -0,0 +1,303 @@
+---
+summary: "Use OpenAI via API keys or Codex subscription in QuantumClaw"
+read_when:
+  - You want to use OpenAI models in QuantumClaw
+  - You want Codex subscription auth instead of API keys
+title: "OpenAI"
+---
+
+# OpenAI
+
+OpenAI provides developer APIs for GPT models. Codex supports **ChatGPT sign-in** for subscription
+access or **API key** sign-in for usage-based access. Codex cloud requires ChatGPT sign-in.
+OpenAI explicitly supports subscription OAuth usage in external tools/workflows like QuantumClaw.
+
+## Option A: OpenAI API key (OpenAI Platform)
+
+**Best for:** direct API access and usage-based billing.
+Get your API key from the OpenAI dashboard.
+
+### CLI setup
+
+```bash
+quantumclaw onboard --auth-choice openai-api-key
+# or non-interactive
+quantumclaw onboard --openai-api-key "$OPENAI_API_KEY"
+```
+
+### Config snippet
+
+```json5
+{
+  env: { OPENAI_API_KEY: "sk-..." },
+  agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
+}
+```
+
+OpenAI's current API model docs list `gpt-5.4` and `gpt-5.4-pro` for direct
+OpenAI API usage. QuantumClaw forwards both through the `openai/*` Responses path.
+QuantumClaw intentionally suppresses the stale `openai/gpt-5.3-codex-spark` row,
+because direct OpenAI API calls reject it in live traffic.
+
+QuantumClaw does **not** expose `openai/gpt-5.3-codex-spark` on the direct OpenAI
+API path. `pi-ai` still ships a built-in row for that model, but live OpenAI API
+requests currently reject it. Spark is treated as Codex-only in QuantumClaw.
+
+## Option B: OpenAI Code (Codex) subscription
+
+**Best for:** using ChatGPT/Codex subscription access instead of an API key.
+Codex cloud requires ChatGPT sign-in, while the Codex CLI supports ChatGPT or API key sign-in.
+
+### CLI setup (Codex OAuth)
+
+```bash
+# Run Codex OAuth in the wizard
+quantumclaw onboard --auth-choice openai-codex
+
+# Or run OAuth directly
+quantumclaw models auth login --provider openai-codex
+```
+
+### Config snippet (Codex subscription)
+
+```json5
+{
+  agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } },
+}
+```
+
+OpenAI's current Codex docs list `gpt-5.4` as the current Codex model. QuantumClaw
+maps that to `openai-codex/gpt-5.4` for ChatGPT/Codex OAuth usage.
+
+If your Codex account is entitled to Codex Spark, QuantumClaw also supports:
+
+- `openai-codex/gpt-5.3-codex-spark`
+
+QuantumClaw treats Codex Spark as Codex-only. It does not expose a direct
+`openai/gpt-5.3-codex-spark` API-key path.
+
+QuantumClaw also preserves `openai-codex/gpt-5.3-codex-spark` when `pi-ai`
+discovers it. Treat it as entitlement-dependent and experimental: Codex Spark is
+separate from GPT-5.4 `/fast`, and availability depends on the signed-in Codex /
+ChatGPT account.
+
+### Transport default
+
+QuantumClaw uses `pi-ai` for model streaming. For both `openai/*` and
+`openai-codex/*`, default transport is `"auto"` (WebSocket-first, then SSE
+fallback).
+
+You can set `agents.defaults.models.<provider/model>.params.transport`:
+
+- `"sse"`: force SSE
+- `"websocket"`: force WebSocket
+- `"auto"`: try WebSocket, then fall back to SSE
+
+For `openai/*` (Responses API), QuantumClaw also enables WebSocket warm-up by
+default (`openaiWsWarmup: true`) when WebSocket transport is used.
+
+Related OpenAI docs:
+
+- [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
+- [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "openai-codex/gpt-5.4" },
+      models: {
+        "openai-codex/gpt-5.4": {
+          params: {
+            transport: "auto",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+### OpenAI WebSocket warm-up
+
+OpenAI docs describe warm-up as optional. QuantumClaw enables it by default for
+`openai/*` to reduce first-turn latency when using WebSocket transport.
+
+### Disable warm-up
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "openai/gpt-5.4": {
+          params: {
+            openaiWsWarmup: false,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+### Enable warm-up explicitly
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "openai/gpt-5.4": {
+          params: {
+            openaiWsWarmup: true,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+### OpenAI priority processing
+
+OpenAI's API exposes priority processing via `service_tier=priority`. In
+QuantumClaw, set `agents.defaults.models["openai/<model>"].params.serviceTier` to
+pass that field through on direct `openai/*` Responses requests.
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "openai/gpt-5.4": {
+          params: {
+            serviceTier: "priority",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Supported values are `auto`, `default`, `flex`, and `priority`.
+
+### OpenAI fast mode
+
+QuantumClaw exposes a shared fast-mode toggle for both `openai/*` and
+`openai-codex/*` sessions:
+
+- Chat/UI: `/fast status|on|off`
+- Config: `agents.defaults.models["<provider>/<model>"].params.fastMode`
+
+When fast mode is enabled, QuantumClaw applies a low-latency OpenAI profile:
+
+- `reasoning.effort = "low"` when the payload does not already specify reasoning
+- `text.verbosity = "low"` when the payload does not already specify verbosity
+- `service_tier = "priority"` for direct `openai/*` Responses calls to `api.openai.com`
+
+Example:
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "openai/gpt-5.4": {
+          params: {
+            fastMode: true,
+          },
+        },
+        "openai-codex/gpt-5.4": {
+          params: {
+            fastMode: true,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Session overrides win over config. Clearing the session override in the Sessions UI
+returns the session to the configured default.
+
+### OpenAI Responses server-side compaction
+
+For direct OpenAI Responses models (`openai/*` using `api: "openai-responses"` with
+`baseUrl` on `api.openai.com`), QuantumClaw now auto-enables OpenAI server-side
+compaction payload hints:
+
+- Forces `store: true` (unless model compat sets `supportsStore: false`)
+- Injects `context_management: [{ type: "compaction", compact_threshold: ... }]`
+
+By default, `compact_threshold` is `70%` of model `contextWindow` (or `80000`
+when unavailable).
+
+### Enable server-side compaction explicitly
+
+Use this when you want to force `context_management` injection on compatible
+Responses models (for example Azure OpenAI Responses):
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "azure-openai-responses/gpt-5.4": {
+          params: {
+            responsesServerCompaction: true,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+### Enable with a custom threshold
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "openai/gpt-5.4": {
+          params: {
+            responsesServerCompaction: true,
+            responsesCompactThreshold: 120000,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+### Disable server-side compaction
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "openai/gpt-5.4": {
+          params: {
+            responsesServerCompaction: false,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+`responsesServerCompaction` only controls `context_management` injection.
+Direct OpenAI Responses models still force `store: true` unless compat sets
+`supportsStore: false`.
+
+## Notes
+
+- Model refs always use `provider/model` (see [/concepts/models](/concepts/models)).
+- Auth details + reuse rules are in [/concepts/oauth](/concepts/oauth).

package/docs/providers/opencode-go.md

@@ -0,0 +1,45 @@
+---
+summary: "Use the OpenCode Go catalog with the shared OpenCode setup"
+read_when:
+  - You want the OpenCode Go catalog
+  - You need the runtime model refs for Go-hosted models
+title: "OpenCode Go"
+---
+
+# OpenCode Go
+
+OpenCode Go is the Go catalog within [OpenCode](/providers/opencode).
+It uses the same `OPENCODE_API_KEY` as the Zen catalog, but keeps the runtime
+provider id `opencode-go` so upstream per-model routing stays correct.
+
+## Supported models
+
+- `opencode-go/kimi-k2.5`
+- `opencode-go/glm-5`
+- `opencode-go/minimax-m2.5`
+
+## CLI setup
+
+```bash
+quantumclaw onboard --auth-choice opencode-go
+# or non-interactive
+quantumclaw onboard --opencode-go-api-key "$OPENCODE_API_KEY"
+```
+
+## Config snippet
+
+```json5
+{
+  env: { OPENCODE_API_KEY: "YOUR_API_KEY_HERE" }, // pragma: allowlist secret
+  agents: { defaults: { model: { primary: "opencode-go/kimi-k2.5" } } },
+}
+```
+
+## Routing behavior
+
+QuantumClaw handles per-model routing automatically when the model ref uses `opencode-go/...`.
+
+## Notes
+
+- Use [OpenCode](/providers/opencode) for the shared onboarding and catalog overview.
+- Runtime refs stay explicit: `opencode/...` for Zen, `opencode-go/...` for Go.

package/docs/providers/opencode.md

@@ -0,0 +1,64 @@
+---
+summary: "Use OpenCode Zen and Go catalogs with QuantumClaw"
+read_when:
+  - You want OpenCode-hosted model access
+  - You want to pick between the Zen and Go catalogs
+title: "OpenCode"
+---
+
+# OpenCode
+
+OpenCode exposes two hosted catalogs in QuantumClaw:
+
+- `opencode/...` for the **Zen** catalog
+- `opencode-go/...` for the **Go** catalog
+
+Both catalogs use the same OpenCode API key. QuantumClaw keeps the runtime provider ids
+split so upstream per-model routing stays correct, but onboarding and docs treat them
+as one OpenCode setup.
+
+## CLI setup
+
+### Zen catalog
+
+```bash
+quantumclaw onboard --auth-choice opencode-zen
+quantumclaw onboard --opencode-zen-api-key "$OPENCODE_API_KEY"
+```
+
+### Go catalog
+
+```bash
+quantumclaw onboard --auth-choice opencode-go
+quantumclaw onboard --opencode-go-api-key "$OPENCODE_API_KEY"
+```
+
+## Config snippet
+
+```json5
+{
+  env: { OPENCODE_API_KEY: "sk-..." },
+  agents: { defaults: { model: { primary: "opencode/claude-opus-4-6" } } },
+}
+```
+
+## Catalogs
+
+### Zen
+
+- Runtime provider: `opencode`
+- Example models: `opencode/claude-opus-4-6`, `opencode/gpt-5.2`, `opencode/gemini-3-pro`
+- Best when you want the curated OpenCode multi-model proxy
+
+### Go
+
+- Runtime provider: `opencode-go`
+- Example models: `opencode-go/kimi-k2.5`, `opencode-go/glm-5`, `opencode-go/minimax-m2.5`
+- Best when you want the OpenCode-hosted Kimi/GLM/MiniMax lineup
+
+## Notes
+
+- `OPENCODE_ZEN_API_KEY` is also supported.
+- Entering one OpenCode key during setup stores credentials for both runtime providers.
+- You sign in to OpenCode, add billing details, and copy your API key.
+- Billing and catalog availability are managed from the OpenCode dashboard.

package/docs/providers/openrouter.md

@@ -0,0 +1,37 @@
+---
+summary: "Use OpenRouter'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 OpenRouter in QuantumClaw
+title: "OpenRouter"
+---
+
+# OpenRouter
+
+OpenRouter 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.
+
+## CLI setup
+
+```bash
+quantumclaw onboard --auth-choice apiKey --token-provider openrouter --token "$OPENROUTER_API_KEY"
+```
+
+## Config snippet
+
+```json5
+{
+  env: { OPENROUTER_API_KEY: "sk-or-..." },
+  agents: {
+    defaults: {
+      model: { primary: "openrouter/anthropic/claude-sonnet-4-6" },
+    },
+  },
+}
+```
+
+## Notes
+
+- Model refs are `openrouter/<provider>/<model>`.
+- For more model/provider options, see [/concepts/model-providers](/concepts/model-providers).
+- OpenRouter uses a Bearer token with your API key under the hood.

package/docs/providers/perplexity-provider.md

@@ -0,0 +1,62 @@
+---
+title: "Perplexity (Provider)"
+summary: "Perplexity web search provider setup (API key, search modes, filtering)"
+read_when:
+  - You want to configure Perplexity as a web search provider
+  - You need the Perplexity API key or OpenRouter proxy setup
+---
+
+# Perplexity (Web Search Provider)
+
+The Perplexity plugin provides web search capabilities through the Perplexity
+Search API or Perplexity Sonar via OpenRouter.
+
+<Note>
+This page covers the Perplexity **provider** setup. For the Perplexity
+**tool** (how the agent uses it), see [Perplexity tool](/tools/perplexity-search).
+</Note>
+
+- Type: web search provider (not a model provider)
+- Auth: `PERPLEXITY_API_KEY` (direct) or `OPENROUTER_API_KEY` (via OpenRouter)
+- Config path: `plugins.entries.perplexity.config.webSearch.apiKey`
+
+## Quick start
+
+1. Set the API key:
+
+```bash
+quantumclaw configure --section web
+```
+
+Or set it directly:
+
+```bash
+quantumclaw config set plugins.entries.perplexity.config.webSearch.apiKey "pplx-xxxxxxxxxxxx"
+```
+
+2. The agent will automatically use Perplexity for web searches when configured.
+
+## Search modes
+
+The plugin auto-selects the transport based on API key prefix:
+
+| Key prefix | Transport                    | Features                                         |
+| ---------- | ---------------------------- | ------------------------------------------------ |
+| `pplx-`    | Native Perplexity Search API | Structured results, domain/language/date filters |
+| `sk-or-`   | OpenRouter (Sonar)           | AI-synthesized answers with citations            |
+
+## Native API filtering
+
+When using the native Perplexity API (`pplx-` key), searches support:
+
+- **Country**: 2-letter country code
+- **Language**: ISO 639-1 language code
+- **Date range**: day, week, month, year
+- **Domain filters**: allowlist/denylist (max 20 domains)
+- **Content budget**: `max_tokens`, `max_tokens_per_page`
+
+## Environment note
+
+If the Gateway runs as a daemon (launchd/systemd), make sure
+`PERPLEXITY_API_KEY` is available to that process (for example, in
+`~/.quantumclaw/.env` or via `env.shellEnv`).

package/docs/providers/qianfan.md

@@ -0,0 +1,38 @@
+---
+summary: "Use Qianfan's unified API to access many models in QuantumClaw"
+read_when:
+  - You want a single API key for many LLMs
+  - You need Baidu Qianfan setup guidance
+title: "Qianfan"
+---
+
+# Qianfan Provider Guide
+
+Qianfan is Baidu's MaaS platform, 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.
+
+## Prerequisites
+
+1. A Baidu Cloud account with Qianfan API access
+2. An API key from the Qianfan console
+3. QuantumClaw installed on your system
+
+## Getting Your API Key
+
+1. Visit the [Qianfan Console](https://console.bce.baidu.com/qianfan/ais/console/apiKey)
+2. Create a new application or select an existing one
+3. Generate an API key (format: `bce-v3/ALTAK-...`)
+4. Copy the API key for use with QuantumClaw
+
+## CLI setup
+
+```bash
+quantumclaw onboard --auth-choice qianfan-api-key
+```
+
+## Related Documentation
+
+- [QuantumClaw Configuration](/gateway/configuration)
+- [Model Providers](/concepts/model-providers)
+- [Agent Setup](/concepts/agent)
+- [Qianfan API Documentation](https://cloud.baidu.com/doc/qianfan-api/s/3m7of64lb)

package/docs/providers/qwen.md

@@ -0,0 +1,53 @@
+---
+summary: "Use Qwen OAuth (free tier) in QuantumClaw"
+read_when:
+  - You want to use Qwen with QuantumClaw
+  - You want free-tier OAuth access to Qwen Coder
+title: "Qwen"
+---
+
+# Qwen
+
+Qwen provides a free-tier OAuth flow for Qwen Coder and Qwen Vision models
+(2,000 requests/day, subject to Qwen rate limits).
+
+## Enable the plugin
+
+```bash
+quantumclaw plugins enable qwen-portal-auth
+```
+
+Restart the Gateway after enabling.
+
+## Authenticate
+
+```bash
+quantumclaw models auth login --provider qwen-portal --set-default
+```
+
+This runs the Qwen device-code OAuth flow and writes a provider entry to your
+`models.json` (plus a `qwen` alias for quick switching).
+
+## Model IDs
+
+- `qwen-portal/coder-model`
+- `qwen-portal/vision-model`
+
+Switch models with:
+
+```bash
+quantumclaw models set qwen-portal/coder-model
+```
+
+## Reuse Qwen Code CLI login
+
+If you already logged in with the Qwen Code CLI, QuantumClaw will sync credentials
+from `~/.qwen/oauth_creds.json` when it loads the auth store. You still need a
+`models.providers.qwen-portal` entry (use the login command above to create one).
+
+## Notes
+
+- Tokens auto-refresh; re-run the login command if refresh fails or access is revoked.
+- Default base URL: `https://portal.qwen.ai/v1` (override with
+  `models.providers.qwen-portal.baseUrl` if Qwen provides a different endpoint).
+- See [Model providers](/concepts/model-providers) for provider-wide rules.

package/docs/providers/sglang.md

@@ -0,0 +1,104 @@
+---
+summary: "Run QuantumClaw with SGLang (OpenAI-compatible self-hosted server)"
+read_when:
+  - You want to run QuantumClaw against a local SGLang server
+  - You want OpenAI-compatible /v1 endpoints with your own models
+title: "SGLang"
+---
+
+# SGLang
+
+SGLang can serve open-source models via an **OpenAI-compatible** HTTP API.
+QuantumClaw can connect to SGLang using the `openai-completions` API.
+
+QuantumClaw can also **auto-discover** available models from SGLang when you opt
+in with `SGLANG_API_KEY` (any value works if your server does not enforce auth)
+and you do not define an explicit `models.providers.sglang` entry.
+
+## Quick start
+
+1. Start SGLang with an OpenAI-compatible server.
+
+Your base URL should expose `/v1` endpoints (for example `/v1/models`,
+`/v1/chat/completions`). SGLang commonly runs on:
+
+- `http://127.0.0.1:30000/v1`
+
+2. Opt in (any value works if no auth is configured):
+
+```bash
+export SGLANG_API_KEY="sglang-local"
+```
+
+3. Run onboarding and choose `SGLang`, or set a model directly:
+
+```bash
+quantumclaw onboard
+```
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "sglang/your-model-id" },
+    },
+  },
+}
+```
+
+## Model discovery (implicit provider)
+
+When `SGLANG_API_KEY` is set (or an auth profile exists) and you **do not**
+define `models.providers.sglang`, QuantumClaw will query:
+
+- `GET http://127.0.0.1:30000/v1/models`
+
+and convert the returned IDs into model entries.
+
+If you set `models.providers.sglang` explicitly, auto-discovery is skipped and
+you must define models manually.
+
+## Explicit configuration (manual models)
+
+Use explicit config when:
+
+- SGLang runs on a different host/port.
+- You want to pin `contextWindow`/`maxTokens` values.
+- Your server requires a real API key (or you want to control headers).
+
+```json5
+{
+  models: {
+    providers: {
+      sglang: {
+        baseUrl: "http://127.0.0.1:30000/v1",
+        apiKey: "${SGLANG_API_KEY}",
+        api: "openai-completions",
+        models: [
+          {
+            id: "your-model-id",
+            name: "Local SGLang Model",
+            reasoning: false,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 128000,
+            maxTokens: 8192,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+## Troubleshooting
+
+- Check the server is reachable:
+
+```bash
+curl http://127.0.0.1:30000/v1/models
+```
+
+- If requests fail with auth errors, set a real `SGLANG_API_KEY` that matches
+  your server configuration, or configure the provider explicitly under
+  `models.providers.sglang`.