@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/providers/openai.md

@@ -0,0 +1,308 @@
+---
+read_when:
+  - 你想在 QuantumClaw 中使用 OpenAI 模型
+  - 你想使用 Codex 订阅身份验证而不是 API 密钥
+summary: 在 QuantumClaw 中通过 API 密钥或 Codex 订阅使用 OpenAI
+title: OpenAI
+x-i18n:
+  generated_at: "2026-03-16T06:26:45Z"
+  model: gpt-5.4
+  provider: openai
+  source_hash: a348d8fca7b809f84c6b90bf6a799e0a070a6e7b98a78b2cd2d747bb3d2b2212
+  source_path: providers/openai.md
+  workflow: 15
+---
+
+# OpenAI
+
+OpenAI 为 GPT 模型提供开发者 API。Codex 支持**ChatGPT 登录**以进行订阅
+访问，也支持**API 密钥**登录以进行按使用量计费的访问。Codex cloud 需要 ChatGPT 登录。
+OpenAI 明确支持在 QuantumClaw 这样的外部工具/工作流中使用订阅 OAuth。
+
+## 选项 A：OpenAI API 密钥（OpenAI Platform）
+
+**最适合：** 直接 API 访问和按使用量计费。
+从 OpenAI 控制台获取你的 API 密钥。
+
+### CLI 设置
+
+```bash
+quantumclaw onboard --auth-choice openai-api-key
+# or non-interactive
+quantumclaw onboard --openai-api-key "$OPENAI_API_KEY"
+```
+
+### 配置片段
+
+```json5
+{
+  env: { OPENAI_API_KEY: "sk-..." },
+  agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
+}
+```
+
+OpenAI 当前的 API 模型文档将 `gpt-5.4` 和 `gpt-5.4-pro` 列为直接
+OpenAI API 用法的模型。QuantumClaw 会通过 `openai/*` Responses 路径转发这两者。
+QuantumClaw 会有意隐藏过时的 `openai/gpt-5.3-codex-spark` 条目，
+因为直接 OpenAI API 调用会在实际流量中拒绝它。
+
+QuantumClaw **不会**在直接 OpenAI
+API 路径上暴露 `openai/gpt-5.3-codex-spark`。`pi-ai` 仍然为该模型提供内置条目，但当前实际 OpenAI API
+请求会拒绝它。在 QuantumClaw 中，Spark 被视为仅限 Codex。
+
+## 选项 B：OpenAI Code（Codex）订阅
+
+**最适合：** 使用 ChatGPT/Codex 订阅访问，而不是 API 密钥。
+Codex cloud 需要 ChatGPT 登录，而 Codex CLI 支持 ChatGPT 或 API 密钥登录。
+
+### CLI 设置（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
+```
+
+### 配置片段（Codex 订阅）
+
+```json5
+{
+  agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } },
+}
+```
+
+OpenAI 当前的 Codex 文档将 `gpt-5.4` 列为当前 Codex 模型。QuantumClaw
+会将其映射为 `openai-codex/gpt-5.4`，用于 ChatGPT/Codex OAuth。
+
+如果你的 Codex 账户有权使用 Codex Spark，QuantumClaw 也支持：
+
+- `openai-codex/gpt-5.3-codex-spark`
+
+QuantumClaw 将 Codex Spark 视为仅限 Codex。它不会暴露直接的
+`openai/gpt-5.3-codex-spark` API 密钥路径。
+
+当 `pi-ai`
+发现 `openai-codex/gpt-5.3-codex-spark` 时，QuantumClaw 也会保留它。请将其视为依赖 entitlement 且处于实验阶段：Codex Spark 与 GPT-5.4 `/fast` 分开，是否可用取决于已登录的 Codex /
+ChatGPT 账户。
+
+### 默认传输
+
+QuantumClaw 使用 `pi-ai` 进行模型流式传输。对于 `openai/*` 和
+`openai-codex/*`，默认传输都是 `"auto"`（优先 WebSocket，然后回退到 SSE）。
+
+你可以设置 `agents.defaults.models.<provider/model>.params.transport`：
+
+- `"sse"`：强制使用 SSE
+- `"websocket"`：强制使用 WebSocket
+- `"auto"`：尝试 WebSocket，然后回退到 SSE
+
+对于 `openai/*`（Responses API），当使用 WebSocket 传输时，
+QuantumClaw 还会默认启用 WebSocket 预热
+（`openaiWsWarmup: true`）。
+
+相关 OpenAI 文档：
+
+- [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 预热
+
+OpenAI 文档将预热描述为可选。QuantumClaw 对
+`openai/*` 默认启用它，以在使用 WebSocket 传输时减少首次响应延迟。
+
+### 禁用预热
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "openai/gpt-5.4": {
+          params: {
+            openaiWsWarmup: false,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+### 显式启用预热
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "openai/gpt-5.4": {
+          params: {
+            openaiWsWarmup: true,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+### OpenAI 优先处理
+
+OpenAI 的 API 通过 `service_tier=priority` 暴露优先处理。在
+QuantumClaw 中，设置 `agents.defaults.models["openai/<model>"].params.serviceTier`，即可
+在直接 `openai/*` Responses 请求中透传该字段。
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "openai/gpt-5.4": {
+          params: {
+            serviceTier: "priority",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+支持的值为 `auto`、`default`、`flex` 和 `priority`。
+
+### OpenAI 快速模式
+
+QuantumClaw 为 `openai/*` 和
+`openai-codex/*` 会话公开了共享快速模式开关：
+
+- 聊天/UI：`/fast status|on|off`
+- 配置：`agents.defaults.models["<provider>/<model>"].params.fastMode`
+
+启用快速模式后，QuantumClaw 会应用低延迟 OpenAI 配置：
+
+- 当负载未明确指定 reasoning 时，设置 `reasoning.effort = "low"`
+- 当负载未明确指定 verbosity 时，设置 `text.verbosity = "low"`
+- 对直接发往 `api.openai.com` 的 `openai/*` Responses 调用设置 `service_tier = "priority"`
+
+示例：
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "openai/gpt-5.4": {
+          params: {
+            fastMode: true,
+          },
+        },
+        "openai-codex/gpt-5.4": {
+          params: {
+            fastMode: true,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+会话覆盖优先于配置。在会话 UI 中清除会话覆盖后，
+该会话会恢复为配置的默认值。
+
+### OpenAI Responses 服务端压缩
+
+对于直接 OpenAI Responses 模型（使用 `api: "openai-responses"` 的 `openai/*`，
+且 `baseUrl` 指向 `api.openai.com`），QuantumClaw 现在会自动启用 OpenAI 服务端
+压缩负载提示：
+
+- 强制设置 `store: true`（除非模型兼容性设置 `supportsStore: false`）
+- 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]`
+
+默认情况下，`compact_threshold` 为模型 `contextWindow` 的 `70%`（或在不可用时为 `80000`）。
+
+### 显式启用服务端压缩
+
+当你想在兼容的
+Responses 模型上强制注入 `context_management` 时使用此设置（例如 Azure OpenAI Responses）：
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "azure-openai-responses/gpt-5.4": {
+          params: {
+            responsesServerCompaction: true,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+### 使用自定义阈值启用
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "openai/gpt-5.4": {
+          params: {
+            responsesServerCompaction: true,
+            responsesCompactThreshold: 120000,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+### 禁用服务端压缩
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "openai/gpt-5.4": {
+          params: {
+            responsesServerCompaction: false,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+`responsesServerCompaction` 仅控制 `context_management` 注入。
+直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性设置
+了 `supportsStore: false`。
+
+## 说明
+
+- 模型引用始终使用 `provider/model`（参见 [/concepts/models](/concepts/models)）。
+- 身份验证详情和复用规则见 [/concepts/oauth](/concepts/oauth)。

package/docs/zh-CN/providers/opencode-go.md

@@ -0,0 +1,52 @@
+---
+read_when:
+  - 你想使用 OpenCode Go 目录
+  - 你需要了解 Go 托管模型的运行时模型引用
+summary: 使用共享的 OpenCode 设置来使用 OpenCode Go 目录
+title: OpenCode Go
+x-i18n:
+  generated_at: "2026-03-16T06:26:48Z"
+  model: gpt-5.4
+  provider: openai
+  source_hash: 8650af7c64220c14bab8c22472fff8bebd7abde253e972b6a11784ad833d321c
+  source_path: providers/opencode-go.md
+  workflow: 15
+---
+
+# OpenCode Go
+
+OpenCode Go 是 [OpenCode](/providers/opencode) 中的 Go 目录。
+它使用与 Zen 目录相同的 `OPENCODE_API_KEY`，但保留运行时
+提供商 id `opencode-go`，以便上游按模型路由保持正确。
+
+## 支持的模型
+
+- `opencode-go/kimi-k2.5`
+- `opencode-go/glm-5`
+- `opencode-go/minimax-m2.5`
+
+## CLI 设置
+
+```bash
+quantumclaw onboard --auth-choice opencode-go
+# 或非交互式
+quantumclaw onboard --opencode-go-api-key "$OPENCODE_API_KEY"
+```
+
+## 配置片段
+
+```json5
+{
+  env: { OPENCODE_API_KEY: "YOUR_API_KEY_HERE" }, // pragma: allowlist secret
+  agents: { defaults: { model: { primary: "opencode-go/kimi-k2.5" } } },
+}
+```
+
+## 路由行为
+
+当模型引用使用 `opencode-go/...` 时，QuantumClaw 会自动处理按模型路由。
+
+## 说明
+
+- 共享的新手引导和目录概览请使用 [OpenCode](/providers/opencode)。
+- 运行时引用保持显式：Zen 使用 `opencode/...`，Go 使用 `opencode-go/...`。

package/docs/zh-CN/providers/opencode.md

@@ -0,0 +1,71 @@
+---
+read_when:
+  - 你想使用 OpenCode 托管的模型访问
+  - 你想在 Zen 和 Go 目录之间进行选择
+summary: 在 QuantumClaw 中使用 OpenCode Zen 和 Go 目录
+title: OpenCode
+x-i18n:
+  generated_at: "2026-03-16T06:26:52Z"
+  model: gpt-5.4
+  provider: openai
+  source_hash: 9ffe65d152d1835163f9f5ae4cc966e29bd01a9dbb88187c24d149c960c8225d
+  source_path: providers/opencode.md
+  workflow: 15
+---
+
+# OpenCode
+
+OpenCode 在 QuantumClaw 中提供两个托管目录：
+
+- `opencode/...` 用于 **Zen** 目录
+- `opencode-go/...` 用于 **Go** 目录
+
+两个目录都使用相同的 OpenCode API 密钥。QuantumClaw 会将运行时提供商 ID
+保持拆分，以便上游按模型路由保持正确，但新手引导和文档将它们视为
+同一个 OpenCode 设置。
+
+## CLI 设置
+
+### Zen 目录
+
+```bash
+quantumclaw onboard --auth-choice opencode-zen
+quantumclaw onboard --opencode-zen-api-key "$OPENCODE_API_KEY"
+```
+
+### Go 目录
+
+```bash
+quantumclaw onboard --auth-choice opencode-go
+quantumclaw onboard --opencode-go-api-key "$OPENCODE_API_KEY"
+```
+
+## 配置片段
+
+```json5
+{
+  env: { OPENCODE_API_KEY: "sk-..." },
+  agents: { defaults: { model: { primary: "opencode/claude-opus-4-6" } } },
+}
+```
+
+## 目录
+
+### Zen
+
+- 运行时提供商：`opencode`
+- 示例模型：`opencode/claude-opus-4-6`、`opencode/gpt-5.2`、`opencode/gemini-3-pro`
+- 适合你想使用精选的 OpenCode 多模型代理时
+
+### Go
+
+- 运行时提供商：`opencode-go`
+- 示例模型：`opencode-go/kimi-k2.5`、`opencode-go/glm-5`、`opencode-go/minimax-m2.5`
+- 适合你想使用 OpenCode 托管的 Kimi/GLM/MiniMax 产品线时
+
+## 说明
+
+- 也支持 `OPENCODE_ZEN_API_KEY`。
+- 在设置期间输入一个 OpenCode 密钥，会为两个运行时提供商都存储凭证。
+- 你需要登录 OpenCode、添加计费信息，然后复制你的 API 密钥。
+- 计费和目录可用性由 OpenCode 仪表板管理。

package/docs/zh-CN/providers/openrouter.md

@@ -0,0 +1,44 @@
+---
+read_when:
+  - 你想用一个 API key 访问许多 LLM
+  - 你想通过 OpenRouter 在 QuantumClaw 中运行模型
+summary: 使用 OpenRouter 的统一 API 在 QuantumClaw 中访问许多模型
+title: OpenRouter
+x-i18n:
+  generated_at: "2026-03-16T06:26:52Z"
+  model: gpt-5.4
+  provider: openai
+  source_hash: b7e29fc9c456c64d567dd909a85166e6dea8388ebd22155a31e69c970e081586
+  source_path: providers/openrouter.md
+  workflow: 15
+---
+
+# OpenRouter
+
+OpenRouter 提供一个**统一 API**，可通过单个
+端点和 API key 将请求路由到许多模型。它与 OpenAI 兼容，因此大多数 OpenAI SDK 只需切换 base URL 即可使用。
+
+## CLI 设置
+
+```bash
+quantumclaw onboard --auth-choice apiKey --token-provider openrouter --token "$OPENROUTER_API_KEY"
+```
+
+## 配置片段
+
+```json5
+{
+  env: { OPENROUTER_API_KEY: "sk-or-..." },
+  agents: {
+    defaults: {
+      model: { primary: "openrouter/anthropic/claude-sonnet-4-5" },
+    },
+  },
+}
+```
+
+## 说明
+
+- 模型引用格式为 `openrouter/<provider>/<model>`。
+- 关于更多模型/提供商选项，请参阅 [/concepts/model-providers](/concepts/model-providers)。
+- OpenRouter 在底层使用带有你的 API key 的 Bearer token。

package/docs/zh-CN/providers/qianfan.md

@@ -0,0 +1,45 @@
+---
+read_when:
+  - 你想用一个 API key 访问许多 LLM
+  - 你需要 Baidu Qianfan 设置指南
+summary: 使用 Qianfan 的统一 API 在 QuantumClaw 中访问许多模型
+title: Qianfan
+x-i18n:
+  generated_at: "2026-03-16T06:26:58Z"
+  model: gpt-5.4
+  provider: openai
+  source_hash: 2ca710b422f190b65d23db51a3219f0abd67074fb385251efeca6eae095d02e0
+  source_path: providers/qianfan.md
+  workflow: 15
+---
+
+# Qianfan 提供商指南
+
+Qianfan 是 Baidu 的 MaaS 平台，提供一个**统一 API**，可通过单个
+端点和 API key 将请求路由到许多模型。它与 OpenAI 兼容，因此大多数 OpenAI SDK 只需切换 base URL 即可使用。
+
+## 前提条件
+
+1. 一个已开通 Qianfan API 访问权限的 Baidu Cloud 账号
+2. 一个来自 Qianfan 控制台的 API key
+3. 已在你的系统上安装 QuantumClaw
+
+## 获取 API key
+
+1. 访问 [Qianfan Console](https://console.bce.baidu.com/qianfan/ais/console/apiKey)
+2. 创建一个新应用，或选择一个现有应用
+3. 生成一个 API key（格式：`bce-v3/ALTAK-...`）
+4. 复制该 API key 以在 QuantumClaw 中使用
+
+## CLI 设置
+
+```bash
+quantumclaw onboard --auth-choice qianfan-api-key
+```
+
+## 相关文档
+
+- [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/zh-CN/providers/qwen.md

@@ -0,0 +1,55 @@
+---
+read_when:
+  - 你想在 QuantumClaw 中使用 Qwen
+  - 你想要免费层 OAuth 访问 Qwen Coder
+summary: 在 QuantumClaw 中使用 Qwen OAuth（免费层）
+title: Qwen
+x-i18n:
+  generated_at: "2026-02-03T07:53:34Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 88b88e224e2fecbb1ca26e24fbccdbe25609be40b38335d0451343a5da53fdd4
+  source_path: providers/qwen.md
+  workflow: 15
+---
+
+# Qwen
+
+Qwen 为 Qwen Coder 和 Qwen Vision 模型提供免费层 OAuth 流程（每天 2,000 次请求，受 Qwen 速率限制约束）。
+
+## 启用插件
+
+```bash
+quantumclaw plugins enable qwen-portal-auth
+```
+
+启用后重启 Gateway 网关。
+
+## 认证
+
+```bash
+quantumclaw models auth login --provider qwen-portal --set-default
+```
+
+这会运行 Qwen 设备码 OAuth 流程并将提供商条目写入你的 `models.json`（加上一个 `qwen` 别名以便快速切换）。
+
+## 模型 ID
+
+- `qwen-portal/coder-model`
+- `qwen-portal/vision-model`
+
+切换模型：
+
+```bash
+quantumclaw models set qwen-portal/coder-model
+```
+
+## 复用 Qwen Code CLI 登录
+
+如果你已经使用 Qwen Code CLI 登录，QuantumClaw 会在加载认证存储时从 `~/.qwen/oauth_creds.json` 同步凭证。你仍然需要一个 `models.providers.qwen-portal` 条目（使用上面的登录命令创建一个）。
+
+## 注意
+
+- 令牌自动刷新；如果刷新失败或访问被撤销，请重新运行登录命令。
+- 默认基础 URL：`https://portal.qwen.ai/v1`（如果 Qwen 提供不同的端点，使用 `models.providers.qwen-portal.baseUrl` 覆盖）。
+- 参阅[模型提供商](/concepts/model-providers)了解提供商级别的规则。

package/docs/zh-CN/providers/sglang.md

@@ -0,0 +1,111 @@
+---
+read_when:
+  - 你想让 QuantumClaw 连接本地 SGLang 服务器运行
+  - 你想通过自己的模型使用兼容 OpenAI 的 `/v1` 端点
+summary: 让 QuantumClaw 与 SGLang 一起运行（兼容 OpenAI 的自托管服务器）
+title: SGLang
+x-i18n:
+  generated_at: "2026-03-16T06:27:01Z"
+  model: gpt-5.4
+  provider: openai
+  source_hash: 26ba858c46bc2b82088274c62270500ffc243e5fb505b8aaaffc096d835187b0
+  source_path: providers/sglang.md
+  workflow: 15
+---
+
+# SGLang
+
+SGLang 可以通过**兼容 OpenAI** 的 HTTP API 提供开源模型服务。
+QuantumClaw 可以使用 `openai-completions` API 连接到 SGLang。
+
+当你通过 `SGLANG_API_KEY` 选择加入时，QuantumClaw 还可以**自动发现**
+SGLang 提供的可用模型（如果你的服务器不强制身份验证，任意值都可）
+并且你没有定义显式的 `models.providers.sglang` 条目。
+
+## 快速开始
+
+1. 使用兼容 OpenAI 的服务器启动 SGLang。
+
+你的基础 URL 应暴露 `/v1` 端点（例如 `/v1/models`、
+`/v1/chat/completions`）。SGLang 通常运行在：
+
+- `http://127.0.0.1:30000/v1`
+
+2. 选择加入（如果未配置身份验证，任意值都可）：
+
+```bash
+export SGLANG_API_KEY="sglang-local"
+```
+
+3. 运行新手引导并选择 `SGLang`，或直接设置模型：
+
+```bash
+quantumclaw onboard
+```
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "sglang/your-model-id" },
+    },
+  },
+}
+```
+
+## 模型发现（隐式提供商）
+
+当设置了 `SGLANG_API_KEY`（或存在 auth profile），并且你**没有**
+定义 `models.providers.sglang` 时，QuantumClaw 将查询：
+
+- `GET http://127.0.0.1:30000/v1/models`
+
+并将返回的 ID 转换为模型条目。
+
+如果你显式设置了 `models.providers.sglang`，则会跳过自动发现，
+你必须手动定义模型。
+
+## 显式配置（手动模型）
+
+在以下情况下使用显式配置：
+
+- SGLang 运行在不同的主机/端口上。
+- 你想固定 `contextWindow`/`maxTokens` 值。
+- 你的服务器需要真实 API 密钥（或者你想控制请求头）。
+
+```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: "本地 SGLang 模型",
+            reasoning: false,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 128000,
+            maxTokens: 8192,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+## 故障排除
+
+- 检查服务器是否可访问：
+
+```bash
+curl http://127.0.0.1:30000/v1/models
+```
+
+- 如果请求因身份验证错误而失败，请设置与
+  你的服务器配置匹配的真实 `SGLANG_API_KEY`，或者在
+  `models.providers.sglang` 下显式配置该提供商。