@quantumclaw/quantumclaw 2026.3.22

package/docs/providers/anthropic.md

@@ -0,0 +1,259 @@
+---
+summary: "Use Anthropic Claude via API keys or setup-token in QuantumClaw"
+read_when:
+  - You want to use Anthropic models in QuantumClaw
+  - You want setup-token instead of API keys
+title: "Anthropic"
+---
+
+# Anthropic (Claude)
+
+Anthropic builds the **Claude** model family and provides access via an API.
+In QuantumClaw you can authenticate with an API key or a **setup-token**.
+
+## Option A: Anthropic API key
+
+**Best for:** standard API access and usage-based billing.
+Create your API key in the Anthropic Console.
+
+### CLI setup
+
+```bash
+quantumclaw onboard
+# choose: Anthropic API key
+
+# or non-interactive
+quantumclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
+```
+
+### Config snippet
+
+```json5
+{
+  env: { ANTHROPIC_API_KEY: "sk-ant-..." },
+  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
+}
+```
+
+## Thinking defaults (Claude 4.6)
+
+- Anthropic Claude 4.6 models default to `adaptive` thinking in QuantumClaw when no explicit thinking level is set.
+- You can override per-message (`/think:<level>`) or in model params:
+  `agents.defaults.models["anthropic/<model>"].params.thinking`.
+- Related Anthropic docs:
+  - [Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking)
+  - [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)
+
+## Fast mode (Anthropic API)
+
+QuantumClaw's shared `/fast` toggle also supports direct Anthropic API-key traffic.
+
+- `/fast on` maps to `service_tier: "auto"`
+- `/fast off` maps to `service_tier: "standard_only"`
+- Config default:
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "anthropic/claude-sonnet-4-6": {
+          params: { fastMode: true },
+        },
+      },
+    },
+  },
+}
+```
+
+Important limits:
+
+- This is **API-key only**. Anthropic setup-token / OAuth auth does not honor QuantumClaw fast-mode tier injection.
+- QuantumClaw only injects Anthropic service tiers for direct `api.anthropic.com` requests. If you route `anthropic/*` through a proxy or gateway, `/fast` leaves `service_tier` untouched.
+- Anthropic reports the effective tier on the response under `usage.service_tier`. On accounts without Priority Tier capacity, `service_tier: "auto"` may still resolve to `standard`.
+
+## Prompt caching (Anthropic API)
+
+QuantumClaw supports Anthropic's prompt caching feature. This is **API-only**; subscription auth does not honor cache settings.
+
+### Configuration
+
+Use the `cacheRetention` parameter in your model config:
+
+| Value   | Cache Duration | Description                         |
+| ------- | -------------- | ----------------------------------- |
+| `none`  | No caching     | Disable prompt caching              |
+| `short` | 5 minutes      | Default for API Key auth            |
+| `long`  | 1 hour         | Extended cache (requires beta flag) |
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "anthropic/claude-opus-4-6": {
+          params: { cacheRetention: "long" },
+        },
+      },
+    },
+  },
+}
+```
+
+### Defaults
+
+When using Anthropic API Key authentication, QuantumClaw automatically applies `cacheRetention: "short"` (5-minute cache) for all Anthropic models. You can override this by explicitly setting `cacheRetention` in your config.
+
+### Per-agent cacheRetention overrides
+
+Use model-level params as your baseline, then override specific agents via `agents.list[].params`.
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "anthropic/claude-opus-4-6" },
+      models: {
+        "anthropic/claude-opus-4-6": {
+          params: { cacheRetention: "long" }, // baseline for most agents
+        },
+      },
+    },
+    list: [
+      { id: "research", default: true },
+      { id: "alerts", params: { cacheRetention: "none" } }, // override for this agent only
+    ],
+  },
+}
+```
+
+Config merge order for cache-related params:
+
+1. `agents.defaults.models["provider/model"].params`
+2. `agents.list[].params` (matching `id`, overrides by key)
+
+This lets one agent keep a long-lived cache while another agent on the same model disables caching to avoid write costs on bursty/low-reuse traffic.
+
+### Bedrock Claude notes
+
+- Anthropic Claude models on Bedrock (`amazon-bedrock/*anthropic.claude*`) accept `cacheRetention` pass-through when configured.
+- Non-Anthropic Bedrock models are forced to `cacheRetention: "none"` at runtime.
+- Anthropic API-key smart defaults also seed `cacheRetention: "short"` for Claude-on-Bedrock model refs when no explicit value is set.
+
+### Legacy parameter
+
+The older `cacheControlTtl` parameter is still supported for backwards compatibility:
+
+- `"5m"` maps to `short`
+- `"1h"` maps to `long`
+
+We recommend migrating to the new `cacheRetention` parameter.
+
+QuantumClaw includes the `extended-cache-ttl-2025-04-11` beta flag for Anthropic API
+requests; keep it if you override provider headers (see [/gateway/configuration](/gateway/configuration)).
+
+## 1M context window (Anthropic beta)
+
+Anthropic's 1M context window is beta-gated. In QuantumClaw, enable it per model
+with `params.context1m: true` for supported Opus/Sonnet models.
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "anthropic/claude-opus-4-6": {
+          params: { context1m: true },
+        },
+      },
+    },
+  },
+}
+```
+
+QuantumClaw maps this to `anthropic-beta: context-1m-2025-08-07` on Anthropic
+requests.
+
+This only activates when `params.context1m` is explicitly set to `true` for
+that model.
+
+Requirement: Anthropic must allow long-context usage on that credential
+(typically API key billing, or a subscription account with Extra Usage
+enabled). Otherwise Anthropic returns:
+`HTTP 429: rate_limit_error: Extra usage is required for long context requests`.
+
+Note: Anthropic currently rejects `context-1m-*` beta requests when using
+OAuth/subscription tokens (`sk-ant-oat-*`). QuantumClaw automatically skips the
+context1m beta header for OAuth auth and keeps the required OAuth betas.
+
+## Option B: Claude setup-token
+
+**Best for:** using your Claude subscription.
+
+### Where to get a setup-token
+
+Setup-tokens are created by the **Claude Code CLI**, not the Anthropic Console. You can run this on **any machine**:
+
+```bash
+claude setup-token
+```
+
+Paste the token into QuantumClaw (wizard: **Anthropic token (paste setup-token)**), or run it on the gateway host:
+
+```bash
+quantumclaw models auth setup-token --provider anthropic
+```
+
+If you generated the token on a different machine, paste it:
+
+```bash
+quantumclaw models auth paste-token --provider anthropic
+```
+
+### CLI setup (setup-token)
+
+```bash
+# Paste a setup-token during setup
+quantumclaw onboard --auth-choice setup-token
+```
+
+### Config snippet (setup-token)
+
+```json5
+{
+  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
+}
+```
+
+## Notes
+
+- Generate the setup-token with `claude setup-token` and paste it, or run `quantumclaw models auth setup-token` on the gateway host.
+- If you see “OAuth token refresh failed …” on a Claude subscription, re-auth with a setup-token. See [/gateway/troubleshooting](/gateway/troubleshooting).
+- Auth details + reuse rules are in [/concepts/oauth](/concepts/oauth).
+
+## Troubleshooting
+
+**401 errors / token suddenly invalid**
+
+- Claude subscription auth can expire or be revoked. Re-run `claude setup-token`
+  and paste it into the **gateway host**.
+- If the Claude CLI login lives on a different machine, use
+  `quantumclaw models auth paste-token --provider anthropic` on the gateway host.
+
+**No API key found for provider "anthropic"**
+
+- Auth is **per agent**. New agents don’t inherit the main agent’s keys.
+- Re-run onboarding for that agent, or paste a setup-token / API key on the
+  gateway host, then verify with `quantumclaw models status`.
+
+**No credentials found for profile `anthropic:default`**
+
+- Run `quantumclaw models status` to see which auth profile is active.
+- Re-run onboarding, or paste a setup-token / API key for that profile.
+
+**No available auth profile (all in cooldown/unavailable)**
+
+- Check `quantumclaw models status --json` for `auth.unusableProfiles`.
+- Add another Anthropic profile or wait for cooldown.
+
+More: [/gateway/troubleshooting](/gateway/troubleshooting) and [/help/faq](/help/faq).

package/docs/providers/bedrock.md

@@ -0,0 +1,176 @@
+---
+summary: "Use Amazon Bedrock (Converse API) models with QuantumClaw"
+read_when:
+  - You want to use Amazon Bedrock models with QuantumClaw
+  - You need AWS credential/region setup for model calls
+title: "Amazon Bedrock"
+---
+
+# Amazon Bedrock
+
+QuantumClaw can use **Amazon Bedrock** models via pi‑ai’s **Bedrock Converse**
+streaming provider. Bedrock auth uses the **AWS SDK default credential chain**,
+not an API key.
+
+## What pi-ai supports
+
+- Provider: `amazon-bedrock`
+- API: `bedrock-converse-stream`
+- Auth: AWS credentials (env vars, shared config, or instance role)
+- Region: `AWS_REGION` or `AWS_DEFAULT_REGION` (default: `us-east-1`)
+
+## Automatic model discovery
+
+If AWS credentials are detected, QuantumClaw can automatically discover Bedrock
+models that support **streaming** and **text output**. Discovery uses
+`bedrock:ListFoundationModels` and is cached (default: 1 hour).
+
+Config options live under `models.bedrockDiscovery`:
+
+```json5
+{
+  models: {
+    bedrockDiscovery: {
+      enabled: true,
+      region: "us-east-1",
+      providerFilter: ["anthropic", "amazon"],
+      refreshInterval: 3600,
+      defaultContextWindow: 32000,
+      defaultMaxTokens: 4096,
+    },
+  },
+}
+```
+
+Notes:
+
+- `enabled` defaults to `true` when AWS credentials are present.
+- `region` defaults to `AWS_REGION` or `AWS_DEFAULT_REGION`, then `us-east-1`.
+- `providerFilter` matches Bedrock provider names (for example `anthropic`).
+- `refreshInterval` is seconds; set to `0` to disable caching.
+- `defaultContextWindow` (default: `32000`) and `defaultMaxTokens` (default: `4096`)
+  are used for discovered models (override if you know your model limits).
+
+## Onboarding
+
+1. Ensure AWS credentials are available on the **gateway host**:
+
+```bash
+export AWS_ACCESS_KEY_ID="AKIA..."
+export AWS_SECRET_ACCESS_KEY="..."
+export AWS_REGION="us-east-1"
+# Optional:
+export AWS_SESSION_TOKEN="..."
+export AWS_PROFILE="your-profile"
+# Optional (Bedrock API key/bearer token):
+export AWS_BEARER_TOKEN_BEDROCK="..."
+```
+
+2. Add a Bedrock provider and model to your config (no `apiKey` required):
+
+```json5
+{
+  models: {
+    providers: {
+      "amazon-bedrock": {
+        baseUrl: "https://bedrock-runtime.us-east-1.amazonaws.com",
+        api: "bedrock-converse-stream",
+        auth: "aws-sdk",
+        models: [
+          {
+            id: "us.anthropic.claude-opus-4-6-v1:0",
+            name: "Claude Opus 4.6 (Bedrock)",
+            reasoning: true,
+            input: ["text", "image"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 200000,
+            maxTokens: 8192,
+          },
+        ],
+      },
+    },
+  },
+  agents: {
+    defaults: {
+      model: { primary: "amazon-bedrock/us.anthropic.claude-opus-4-6-v1:0" },
+    },
+  },
+}
+```
+
+## EC2 Instance Roles
+
+When running QuantumClaw on an EC2 instance with an IAM role attached, the AWS SDK
+will automatically use the instance metadata service (IMDS) for authentication.
+However, QuantumClaw's credential detection currently only checks for environment
+variables, not IMDS credentials.
+
+**Workaround:** Set `AWS_PROFILE=default` to signal that AWS credentials are
+available. The actual authentication still uses the instance role via IMDS.
+
+```bash
+# Add to ~/.bashrc or your shell profile
+export AWS_PROFILE=default
+export AWS_REGION=us-east-1
+```
+
+**Required IAM permissions** for the EC2 instance role:
+
+- `bedrock:InvokeModel`
+- `bedrock:InvokeModelWithResponseStream`
+- `bedrock:ListFoundationModels` (for automatic discovery)
+
+Or attach the managed policy `AmazonBedrockFullAccess`.
+
+## Quick setup (AWS path)
+
+```bash
+# 1. Create IAM role and instance profile
+aws iam create-role --role-name EC2-Bedrock-Access \
+  --assume-role-policy-document '{
+    "Version": "2012-10-17",
+    "Statement": [{
+      "Effect": "Allow",
+      "Principal": {"Service": "ec2.amazonaws.com"},
+      "Action": "sts:AssumeRole"
+    }]
+  }'
+
+aws iam attach-role-policy --role-name EC2-Bedrock-Access \
+  --policy-arn arn:aws:iam::aws:policy/AmazonBedrockFullAccess
+
+aws iam create-instance-profile --instance-profile-name EC2-Bedrock-Access
+aws iam add-role-to-instance-profile \
+  --instance-profile-name EC2-Bedrock-Access \
+  --role-name EC2-Bedrock-Access
+
+# 2. Attach to your EC2 instance
+aws ec2 associate-iam-instance-profile \
+  --instance-id i-xxxxx \
+  --iam-instance-profile Name=EC2-Bedrock-Access
+
+# 3. On the EC2 instance, enable discovery
+quantumclaw config set models.bedrockDiscovery.enabled true
+quantumclaw config set models.bedrockDiscovery.region us-east-1
+
+# 4. Set the workaround env vars
+echo 'export AWS_PROFILE=default' >> ~/.bashrc
+echo 'export AWS_REGION=us-east-1' >> ~/.bashrc
+source ~/.bashrc
+
+# 5. Verify models are discovered
+quantumclaw models list
+```
+
+## Notes
+
+- Bedrock requires **model access** enabled in your AWS account/region.
+- Automatic discovery needs the `bedrock:ListFoundationModels` permission.
+- If you use profiles, set `AWS_PROFILE` on the gateway host.
+- QuantumClaw surfaces the credential source in this order: `AWS_BEARER_TOKEN_BEDROCK`,
+  then `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`, then `AWS_PROFILE`, then the
+  default AWS SDK chain.
+- Reasoning support depends on the model; check the Bedrock model card for
+  current capabilities.
+- If you prefer a managed key flow, you can also place an OpenAI‑compatible
+  proxy in front of Bedrock and configure it as an OpenAI provider instead.

package/docs/providers/claude-max-api-proxy.md

@@ -0,0 +1,154 @@
+---
+summary: "Community proxy to expose Claude subscription credentials as an OpenAI-compatible endpoint"
+read_when:
+  - You want to use Claude Max subscription with OpenAI-compatible tools
+  - You want a local API server that wraps Claude Code CLI
+  - You want to evaluate subscription-based vs API-key-based Anthropic access
+title: "Claude Max API Proxy"
+---
+
+# Claude Max API Proxy
+
+**claude-max-api-proxy** is a community tool that exposes your Claude Max/Pro subscription as an OpenAI-compatible API endpoint. This allows you to use your subscription with any tool that supports the OpenAI API format.
+
+<Warning>
+This path is technical compatibility only. Anthropic has blocked some subscription
+usage outside Claude Code in the past. You must decide for yourself whether to use
+it and verify Anthropic's current terms before relying on it.
+</Warning>
+
+## Why Use This?
+
+| Approach                | Cost                                                | Best For                                   |
+| ----------------------- | --------------------------------------------------- | ------------------------------------------ |
+| Anthropic API           | Pay per token (~$15/M input, $75/M output for Opus) | Production apps, high volume               |
+| Claude Max subscription | $200/month flat                                     | Personal use, development, unlimited usage |
+
+If you have a Claude Max subscription and want to use it with OpenAI-compatible tools, this proxy may reduce cost for some workflows. API keys remain the clearer policy path for production use.
+
+## How It Works
+
+```
+Your App → claude-max-api-proxy → Claude Code CLI → Anthropic (via subscription)
+     (OpenAI format)              (converts format)      (uses your login)
+```
+
+The proxy:
+
+1. Accepts OpenAI-format requests at `http://localhost:3456/v1/chat/completions`
+2. Converts them to Claude Code CLI commands
+3. Returns responses in OpenAI format (streaming supported)
+
+## Installation
+
+```bash
+# Requires Node.js 20+ and Claude Code CLI
+npm install -g claude-max-api-proxy
+
+# Verify Claude CLI is authenticated
+claude --version
+```
+
+## Usage
+
+### Start the server
+
+```bash
+claude-max-api
+# Server runs at http://localhost:3456
+```
+
+### Test it
+
+```bash
+# Health check
+curl http://localhost:3456/health
+
+# List models
+curl http://localhost:3456/v1/models
+
+# Chat completion
+curl http://localhost:3456/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "claude-opus-4",
+    "messages": [{"role": "user", "content": "Hello!"}]
+  }'
+```
+
+### With QuantumClaw
+
+You can point QuantumClaw at the proxy as a custom OpenAI-compatible endpoint:
+
+```json5
+{
+  env: {
+    OPENAI_API_KEY: "not-needed",
+    OPENAI_BASE_URL: "http://localhost:3456/v1",
+  },
+  agents: {
+    defaults: {
+      model: { primary: "openai/claude-opus-4" },
+    },
+  },
+}
+```
+
+## Available Models
+
+| Model ID          | Maps To         |
+| ----------------- | --------------- |
+| `claude-opus-4`   | Claude Opus 4   |
+| `claude-sonnet-4` | Claude Sonnet 4 |
+| `claude-haiku-4`  | Claude Haiku 4  |
+
+## Auto-Start on macOS
+
+Create a LaunchAgent to run the proxy automatically:
+
+```bash
+cat > ~/Library/LaunchAgents/com.claude-max-api.plist << 'EOF'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.claude-max-api</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/local/bin/node</string>
+    <string>/usr/local/lib/node_modules/claude-max-api-proxy/dist/server/standalone.js</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>/usr/local/bin:/opt/homebrew/bin:~/.local/bin:/usr/bin:/bin</string>
+  </dict>
+</dict>
+</plist>
+EOF
+
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude-max-api.plist
+```
+
+## Links
+
+- **npm:** [https://www.npmjs.com/package/claude-max-api-proxy](https://www.npmjs.com/package/claude-max-api-proxy)
+- **GitHub:** [https://github.com/atalovesyou/claude-max-api-proxy](https://github.com/atalovesyou/claude-max-api-proxy)
+- **Issues:** [https://github.com/atalovesyou/claude-max-api-proxy/issues](https://github.com/atalovesyou/claude-max-api-proxy/issues)
+
+## Notes
+
+- This is a **community tool**, not officially supported by Anthropic or QuantumClaw
+- Requires an active Claude Max/Pro subscription with Claude Code CLI authenticated
+- The proxy runs locally and does not send data to any third-party servers
+- Streaming responses are fully supported
+
+## See Also
+
+- [Anthropic provider](/providers/anthropic) - Native QuantumClaw integration with Claude setup-token or API keys
+- [OpenAI provider](/providers/openai) - For OpenAI/Codex subscriptions

package/docs/providers/cloudflare-ai-gateway.md

@@ -0,0 +1,71 @@
+---
+title: "Cloudflare AI Gateway"
+summary: "Cloudflare AI Gateway setup (auth + model selection)"
+read_when:
+  - You want to use Cloudflare AI Gateway with QuantumClaw
+  - You need the account ID, gateway ID, or API key env var
+---
+
+# Cloudflare AI Gateway
+
+Cloudflare AI Gateway sits in front of provider APIs and lets you add analytics, caching, and controls. For Anthropic, QuantumClaw uses the Anthropic Messages API through your Gateway endpoint.
+
+- Provider: `cloudflare-ai-gateway`
+- Base URL: `https://gateway.ai.cloudflare.com/v1/<account_id>/<gateway_id>/anthropic`
+- Default model: `cloudflare-ai-gateway/claude-sonnet-4-6`
+- API key: `CLOUDFLARE_AI_GATEWAY_API_KEY` (your provider API key for requests through the Gateway)
+
+For Anthropic models, use your Anthropic API key.
+
+## Quick start
+
+1. Set the provider API key and Gateway details:
+
+```bash
+quantumclaw onboard --auth-choice cloudflare-ai-gateway-api-key
+```
+
+2. Set a default model:
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "cloudflare-ai-gateway/claude-sonnet-4-6" },
+    },
+  },
+}
+```
+
+## Non-interactive example
+
+```bash
+quantumclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice cloudflare-ai-gateway-api-key \
+  --cloudflare-ai-gateway-account-id "your-account-id" \
+  --cloudflare-ai-gateway-gateway-id "your-gateway-id" \
+  --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY"
+```
+
+## Authenticated gateways
+
+If you enabled Gateway authentication in Cloudflare, add the `cf-aig-authorization` header (this is in addition to your provider API key).
+
+```json5
+{
+  models: {
+    providers: {
+      "cloudflare-ai-gateway": {
+        headers: {
+          "cf-aig-authorization": "Bearer <cloudflare-ai-gateway-token>",
+        },
+      },
+    },
+  },
+}
+```
+
+## Environment note
+
+If the Gateway runs as a daemon (launchd/systemd), make sure `CLOUDFLARE_AI_GATEWAY_API_KEY` is available to that process (for example, in `~/.quantumclaw/.env` or via `env.shellEnv`).