@quantumclaw/quantumclaw 2026.3.22

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

@@ -0,0 +1,265 @@
+---
+read_when:
+  - 你想在 QuantumClaw 中使用 Anthropic 模型
+  - 你想使用 setup-token 而不是 API 密钥
+summary: 在 QuantumClaw 中通过 API 密钥或 setup-token 使用 Anthropic Claude
+title: Anthropic
+x-i18n:
+  generated_at: "2026-03-16T06:25:19Z"
+  model: gpt-5.4
+  provider: openai
+  source_hash: b18eff35b652d8dc4b6d55e9051d35682511909b3168be868fa172038294d20b
+  source_path: providers/anthropic.md
+  workflow: 15
+---
+
+# Anthropic（Claude）
+
+Anthropic 构建了 **Claude** 模型家族，并通过 API 提供访问。
+在 QuantumClaw 中，你可以使用 API 密钥或 **setup-token** 进行身份验证。
+
+## 选项 A：Anthropic API 密钥
+
+**最适合：** 标准 API 访问和按使用量计费。
+请在 Anthropic Console 中创建你的 API 密钥。
+
+### CLI 设置
+
+```bash
+quantumclaw onboard
+# choose: Anthropic API key
+
+# or non-interactive
+quantumclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
+```
+
+### 配置片段
+
+```json5
+{
+  env: { ANTHROPIC_API_KEY: "sk-ant-..." },
+  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
+}
+```
+
+## Thinking 默认值（Claude 4.6）
+
+- 当未设置显式 thinking 级别时，Anthropic Claude 4.6 模型在 QuantumClaw 中默认使用 `adaptive` thinking。
+- 你可以按消息覆盖（`/think:<level>`），或在模型参数中覆盖：
+  `agents.defaults.models["anthropic/<model>"].params.thinking`。
+- 相关 Anthropic 文档：
+  - [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)
+
+## 快速模式（Anthropic API）
+
+QuantumClaw 的共享 `/fast` 开关也支持直接 Anthropic API 密钥流量。
+
+- `/fast on` 映射到 `service_tier: "auto"`
+- `/fast off` 映射到 `service_tier: "standard_only"`
+- 配置默认值：
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "anthropic/claude-sonnet-4-5": {
+          params: { fastMode: true },
+        },
+      },
+    },
+  },
+}
+```
+
+重要限制：
+
+- 这**仅适用于 API 密钥**。Anthropic setup-token / OAuth 身份验证不会遵循 QuantumClaw 的快速模式层级注入。
+- QuantumClaw 仅对直接发往 `api.anthropic.com` 的请求注入 Anthropic 服务层级。如果你通过代理或网关路由 `anthropic/*`，`/fast` 不会修改 `service_tier`。
+- Anthropic 会在响应中的 `usage.service_tier` 下报告实际生效的层级。对于没有 Priority Tier 容量的账户，`service_tier: "auto"` 仍可能解析为 `standard`。
+
+## Prompt 缓存（Anthropic API）
+
+QuantumClaw 支持 Anthropic 的 prompt 缓存功能。这**仅适用于 API**；订阅身份验证不会遵循缓存设置。
+
+### 配置
+
+在你的模型配置中使用 `cacheRetention` 参数：
+
+| 值      | 缓存时长 | 说明                       |
+| ------- | -------- | -------------------------- |
+| `none`  | 不缓存   | 禁用 prompt 缓存           |
+| `short` | 5 分钟   | API 密钥身份验证的默认值   |
+| `long`  | 1 小时   | 扩展缓存（需要 beta 标志） |
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "anthropic/claude-opus-4-6": {
+          params: { cacheRetention: "long" },
+        },
+      },
+    },
+  },
+}
+```
+
+### 默认值
+
+当使用 Anthropic API 密钥身份验证时，QuantumClaw 会自动对所有 Anthropic 模型应用 `cacheRetention: "short"`（5 分钟缓存）。你可以通过在配置中显式设置 `cacheRetention` 来覆盖此行为。
+
+### 每个智能体的 cacheRetention 覆盖
+
+将模型级参数用作基线，然后通过 `agents.list[].params` 覆盖特定智能体。
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "anthropic/claude-opus-4-6" },
+      models: {
+        "anthropic/claude-opus-4-6": {
+          params: { cacheRetention: "long" }, // 大多数智能体的基线
+        },
+      },
+    },
+    list: [
+      { id: "research", default: true },
+      { id: "alerts", params: { cacheRetention: "none" } }, // 仅对该智能体覆盖
+    ],
+  },
+}
+```
+
+与缓存相关参数的配置合并顺序：
+
+1. `agents.defaults.models["provider/model"].params`
+2. `agents.list[].params`（匹配 `id`，按键覆盖）
+
+这使得一个智能体可以保留长生命周期缓存，而同一模型上的另一个智能体可以禁用缓存，以避免在突发/低复用流量上产生写入成本。
+
+### Bedrock Claude 说明
+
+- 当已配置时，Bedrock 上的 Anthropic Claude 模型（`amazon-bedrock/*anthropic.claude*`）接受透传的 `cacheRetention`。
+- 非 Anthropic 的 Bedrock 模型会在运行时被强制设置为 `cacheRetention: "none"`。
+- 当未设置显式值时，Anthropic API 密钥的智能默认值也会为 Bedrock 上的 Claude 模型引用填入 `cacheRetention: "short"`。
+
+### 旧版参数
+
+旧的 `cacheControlTtl` 参数仍受支持，以保持向后兼容：
+
+- `"5m"` 映射为 `short`
+- `"1h"` 映射为 `long`
+
+我们建议迁移到新的 `cacheRetention` 参数。
+
+QuantumClaw 会在 Anthropic API 请求中包含 `extended-cache-ttl-2025-04-11` beta 标志；
+如果你覆盖了提供商请求头，请保留它（参见 [/gateway/configuration](/gateway/configuration)）。
+
+## 1M 上下文窗口（Anthropic beta）
+
+Anthropic 的 1M 上下文窗口受 beta 门控。在 QuantumClaw 中，可通过为受支持的 Opus/Sonnet 模型
+设置 `params.context1m: true` 按模型启用。
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "anthropic/claude-opus-4-6": {
+          params: { context1m: true },
+        },
+      },
+    },
+  },
+}
+```
+
+QuantumClaw 会将其映射为 Anthropic 请求上的 `anthropic-beta: context-1m-2025-08-07`。
+
+仅当该模型的 `params.context1m` 被显式设置为 `true` 时，
+此功能才会激活。
+
+要求：Anthropic 必须允许该凭证使用长上下文
+（通常是 API 密钥计费，或启用了 Extra Usage 的订阅账户）。
+否则 Anthropic 会返回：
+`HTTP 429: rate_limit_error: Extra usage is required for long context requests`。
+
+注意：Anthropic 当前在使用
+OAuth/订阅令牌（`sk-ant-oat-*`）时会拒绝 `context-1m-*` beta 请求。QuantumClaw 会自动跳过
+OAuth 身份验证的 `context1m` beta 请求头，并保留所需的 OAuth beta 标志。
+
+## 选项 B：Claude setup-token
+
+**最适合：** 使用你的 Claude 订阅。
+
+### 如何获取 setup-token
+
+setup-token 由 **Claude Code CLI** 创建，而不是在 Anthropic Console 中创建。你可以在**任何机器**上运行：
+
+```bash
+claude setup-token
+```
+
+将该令牌粘贴到 QuantumClaw 中（向导：**Anthropic token（粘贴 setup-token）**），或在 Gateway 网关主机上运行：
+
+```bash
+quantumclaw models auth setup-token --provider anthropic
+```
+
+如果你是在另一台机器上生成该令牌，请粘贴它：
+
+```bash
+quantumclaw models auth paste-token --provider anthropic
+```
+
+### CLI 设置（setup-token）
+
+```bash
+# Paste a setup-token during setup
+quantumclaw onboard --auth-choice setup-token
+```
+
+### 配置片段（setup-token）
+
+```json5
+{
+  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
+}
+```
+
+## 说明
+
+- 使用 `claude setup-token` 生成 setup-token 并粘贴它，或者在 Gateway 网关主机上运行 `quantumclaw models auth setup-token`。
+- 如果你在 Claude 订阅上看到 “OAuth token refresh failed …”，请使用 setup-token 重新进行身份验证。请参见 [/gateway/troubleshooting#oauth-token-refresh-failed-anthropic-claude-subscription](/gateway/troubleshooting#oauth-token-refresh-failed-anthropic-claude-subscription)。
+- 身份验证详情和复用规则见 [/concepts/oauth](/concepts/oauth)。
+
+## 故障排除
+
+**401 错误 / 令牌突然无效**
+
+- Claude 订阅身份验证可能会过期或被撤销。请重新运行 `claude setup-token`，
+  并将其粘贴到 **Gateway 网关主机** 上。
+- 如果 Claude CLI 登录位于另一台机器上，请在 Gateway 网关主机上使用
+  `quantumclaw models auth paste-token --provider anthropic`。
+
+**No API key found for provider "anthropic"**
+
+- 身份验证是**按智能体**区分的。新智能体不会继承主智能体的密钥。
+- 请为该智能体重新运行新手引导，或在
+  Gateway 网关主机上粘贴 setup-token / API 密钥，然后使用 `quantumclaw models status` 验证。
+
+**No credentials found for profile `anthropic:default`**
+
+- 运行 `quantumclaw models status` 查看当前活动的 auth profile。
+- 重新运行新手引导，或为该配置档案粘贴 setup-token / API 密钥。
+
+**No available auth profile (all in cooldown/unavailable)**
+
+- 检查 `quantumclaw models status --json` 中的 `auth.unusableProfiles`。
+- 添加另一个 Anthropic 配置档案，或等待冷却结束。
+
+更多信息：[/gateway/troubleshooting](/gateway/troubleshooting) 和 [/help/faq](/help/faq)。

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

@@ -0,0 +1,170 @@
+---
+read_when:
+  - 你想在 QuantumClaw 中使用 Amazon Bedrock 模型
+  - 你需要为模型调用配置 AWS 凭证/区域
+summary: 在 QuantumClaw 中使用 Amazon Bedrock（Converse API）模型
+title: Amazon Bedrock
+x-i18n:
+  generated_at: "2026-02-03T10:04:01Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 318f1048451a1910b70522e2f7f9dfc87084de26d9e3938a29d372eed32244a8
+  source_path: providers/bedrock.md
+  workflow: 15
+---
+
+# Amazon Bedrock
+
+QuantumClaw 可以通过 pi‑ai 的 **Bedrock Converse** 流式提供商使用 **Amazon Bedrock** 模型。Bedrock 认证使用 **AWS SDK 默认凭证链**，而非 API 密钥。
+
+## pi‑ai 支持的功能
+
+- 提供商：`amazon-bedrock`
+- API：`bedrock-converse-stream`
+- 认证：AWS 凭证（环境变量、共享配置或实例角色）
+- 区域：`AWS_REGION` 或 `AWS_DEFAULT_REGION`（默认：`us-east-1`）
+
+## 自动模型发现
+
+如果检测到 AWS 凭证，QuantumClaw 可以自动发现支持**流式传输**和**文本输出**的 Bedrock 模型。发现功能使用 `bedrock:ListFoundationModels`，并会被缓存（默认：1 小时）。
+
+配置选项位于 `models.bedrockDiscovery` 下：
+
+```json5
+{
+  models: {
+    bedrockDiscovery: {
+      enabled: true,
+      region: "us-east-1",
+      providerFilter: ["anthropic", "amazon"],
+      refreshInterval: 3600,
+      defaultContextWindow: 32000,
+      defaultMaxTokens: 4096,
+    },
+  },
+}
+```
+
+注意事项：
+
+- `enabled` 在存在 AWS 凭证时默认为 `true`。
+- `region` 默认为 `AWS_REGION` 或 `AWS_DEFAULT_REGION`，然后是 `us-east-1`。
+- `providerFilter` 匹配 Bedrock 提供商名称（例如 `anthropic`）。
+- `refreshInterval` 单位为秒；设置为 `0` 可禁用缓存。
+- `defaultContextWindow`（默认：`32000`）和 `defaultMaxTokens`（默认：`4096`）用于已发现的模型（如果你知道模型限制，可以覆盖这些值）。
+
+## 设置（手动）
+
+1. 确保 AWS 凭证在 **Gateway 网关主机**上可用：
+
+```bash
+export AWS_ACCESS_KEY_ID="AKIA..."
+export AWS_SECRET_ACCESS_KEY="..."
+export AWS_REGION="us-east-1"
+# 可选：
+export AWS_SESSION_TOKEN="..."
+export AWS_PROFILE="your-profile"
+# 可选（Bedrock API 密钥/Bearer 令牌）：
+export AWS_BEARER_TOKEN_BEDROCK="..."
+```
+
+2. 在配置中添加 Bedrock 提供商和模型（无需 `apiKey`）：
+
+```json5
+{
+  models: {
+    providers: {
+      "amazon-bedrock": {
+        baseUrl: "https://bedrock-runtime.us-east-1.amazonaws.com",
+        api: "bedrock-converse-stream",
+        auth: "aws-sdk",
+        models: [
+          {
+            id: "anthropic.claude-opus-4-5-20251101-v1:0",
+            name: "Claude Opus 4.5 (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/anthropic.claude-opus-4-5-20251101-v1:0" },
+    },
+  },
+}
+```
+
+## EC2 实例角色
+
+当在附加了 IAM 角色的 EC2 实例上运行 QuantumClaw 时，AWS SDK 会自动使用实例元数据服务（IMDS）进行认证。但是，QuantumClaw 的凭证检测目前只检查环境变量，不检查 IMDS 凭证。
+
+**解决方法：** 设置 `AWS_PROFILE=default` 以表明 AWS 凭证可用。实际认证仍然通过 IMDS 使用实例角色。
+
+```bash
+# 添加到 ~/.bashrc 或你的 shell 配置文件
+export AWS_PROFILE=default
+export AWS_REGION=us-east-1
+```
+
+EC2 实例角色**所需的 IAM 权限**：
+
+- `bedrock:InvokeModel`
+- `bedrock:InvokeModelWithResponseStream`
+- `bedrock:ListFoundationModels`（用于自动发现）
+
+或者附加托管策略 `AmazonBedrockFullAccess`。
+
+**快速设置：**
+
+```bash
+# 1. 创建 IAM 角色和实例配置文件
+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. 附加到你的 EC2 实例
+aws ec2 associate-iam-instance-profile \
+  --instance-id i-xxxxx \
+  --iam-instance-profile Name=EC2-Bedrock-Access
+
+# 3. 在 EC2 实例上启用发现功能
+quantumclaw config set models.bedrockDiscovery.enabled true
+quantumclaw config set models.bedrockDiscovery.region us-east-1
+
+# 4. 设置解决方法所需的环境变量
+echo 'export AWS_PROFILE=default' >> ~/.bashrc
+echo 'export AWS_REGION=us-east-1' >> ~/.bashrc
+source ~/.bashrc
+
+# 5. 验证模型已被发现
+quantumclaw models list
+```
+
+## 注意事项
+
+- Bedrock 需要在你的 AWS 账户/区域中启用**模型访问**。
+- 自动发现需要 `bedrock:ListFoundationModels` 权限。
+- 如果你使用配置文件，请在 Gateway 网关主机上设置 `AWS_PROFILE`。
+- QuantumClaw 按以下顺序获取凭证来源：`AWS_BEARER_TOKEN_BEDROCK`，然后是 `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`，然后是 `AWS_PROFILE`，最后是默认的 AWS SDK 链。
+- 推理支持取决于模型；请查看 Bedrock 模型卡了解当前功能。
+- 如果你更喜欢托管密钥流程，也可以在 Bedrock 前面放置一个 OpenAI 兼容的代理，并将其配置为 OpenAI 提供商。

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

@@ -0,0 +1,155 @@
+---
+read_when:
+  - 你想将 Claude Max 订阅与 OpenAI 兼容工具配合使用
+  - 你想要一个封装 Claude Code CLI 的本地 API 服务器
+  - 你想通过使用订阅而非 API 密钥来节省费用
+summary: 将 Claude Max/Pro 订阅用作 OpenAI 兼容的 API 端点
+title: Claude Max API 代理
+x-i18n:
+  generated_at: "2026-02-01T21:34:52Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 63b61096b96b720c6d0c317520852db65d72ca8279b3868f35e8387fe3b6ce41
+  source_path: providers/claude-max-api-proxy.md
+  workflow: 15
+---
+
+# Claude Max API 代理
+
+**claude-max-api-proxy** 是一个社区工具，将你的 Claude Max/Pro 订阅暴露为 OpenAI 兼容的 API 端点。这使你可以将订阅与任何支持 OpenAI API 格式的工具配合使用。
+
+## 为什么使用它？
+
+| 方式            | 费用                                            | 适用场景                 |
+| --------------- | ----------------------------------------------- | ------------------------ |
+| Anthropic API   | 按 token 计费（Opus 约 $15/M 输入，$75/M 输出） | 生产应用、高流量场景     |
+| Claude Max 订阅 | 每月固定 $200                                   | 个人使用、开发、无限用量 |
+
+如果你有 Claude Max 订阅并希望与 OpenAI 兼容工具配合使用，这个代理可以帮你节省大量费用。
+
+## 工作原理
+
+```
+你的应用 → claude-max-api-proxy → Claude Code CLI → Anthropic（通过订阅）
+     （OpenAI 格式）              （转换格式）           （使用你的登录凭据）
+```
+
+该代理：
+
+1. 在 `http://localhost:3456/v1/chat/completions` 接受 OpenAI 格式的请求
+2. 将其转换为 Claude Code CLI 命令
+3. 以 OpenAI 格式返回响应（支持流式传输）
+
+## 安装
+
+```bash
+# 需要 Node.js 20+ 和 Claude Code CLI
+npm install -g claude-max-api-proxy
+
+# 验证 Claude CLI 已认证
+claude --version
+```
+
+## 使用方法
+
+### 启动服务器
+
+```bash
+claude-max-api
+# 服务器运行在 http://localhost:3456
+```
+
+### 测试
+
+```bash
+# 健康检查
+curl http://localhost:3456/health
+
+# 列出模型
+curl http://localhost:3456/v1/models
+
+# 聊天补全
+curl http://localhost:3456/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "claude-opus-4",
+    "messages": [{"role": "user", "content": "Hello!"}]
+  }'
+```
+
+### 与 QuantumClaw 配合使用
+
+你可以将 QuantumClaw 指向该代理作为自定义 OpenAI 兼容端点：
+
+```json5
+{
+  env: {
+    OPENAI_API_KEY: "not-needed",
+    OPENAI_BASE_URL: "http://localhost:3456/v1",
+  },
+  agents: {
+    defaults: {
+      model: { primary: "openai/claude-opus-4" },
+    },
+  },
+}
+```
+
+## 可用模型
+
+| 模型 ID           | 对应模型        |
+| ----------------- | --------------- |
+| `claude-opus-4`   | Claude Opus 4   |
+| `claude-sonnet-4` | Claude Sonnet 4 |
+| `claude-haiku-4`  | Claude Haiku 4  |
+
+## macOS 自动启动
+
+创建 LaunchAgent 以自动运行代理：
+
+```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
+```
+
+## 链接
+
+- **npm:** https://www.npmjs.com/package/claude-max-api-proxy
+- **GitHub:** https://github.com/atalovesyou/claude-max-api-proxy
+- **Issues:** https://github.com/atalovesyou/claude-max-api-proxy/issues
+
+## 注意事项
+
+- 这是一个**社区工具**，并非由 Anthropic 或 QuantumClaw 官方支持
+- 需要有效的 Claude Max/Pro 订阅并已认证 Claude Code CLI
+- 代理在本地运行，不会将数据发送到任何第三方服务器
+- 完全支持流式响应
+
+## 另请参阅
+
+- [Anthropic 提供商](/providers/anthropic) - QuantumClaw 与 Claude 的原生集成，使用 setup-token 或 API 密钥
+- [OpenAI 提供商](/providers/openai) - 适用于 OpenAI/Codex 订阅

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

@@ -0,0 +1,78 @@
+---
+read_when:
+  - 你想将 Cloudflare AI Gateway 与 QuantumClaw 一起使用
+  - 你需要 account ID、gateway ID 或 API key 环境变量
+summary: Cloudflare AI Gateway 设置（认证 + 模型选择）
+title: Cloudflare AI Gateway
+x-i18n:
+  generated_at: "2026-03-16T06:25:05Z"
+  model: gpt-5.4
+  provider: openai
+  source_hash: db77652c37652ca20f7c50f32382dbaeaeb50ea5bdeaf1d4fd17dc394e58950c
+  source_path: providers/cloudflare-ai-gateway.md
+  workflow: 15
+---
+
+# Cloudflare AI Gateway
+
+Cloudflare AI Gateway 位于提供商 API 前方，让你能够添加分析、缓存和控制功能。对于 Anthropic，QuantumClaw 会通过你的 Gateway 端点使用 Anthropic Messages API。
+
+- 提供商：`cloudflare-ai-gateway`
+- Base URL：`https://gateway.ai.cloudflare.com/v1/<account_id>/<gateway_id>/anthropic`
+- 默认模型：`cloudflare-ai-gateway/claude-sonnet-4-5`
+- API key：`CLOUDFLARE_AI_GATEWAY_API_KEY`（你用于通过 Gateway 发起请求的提供商 API key）
+
+对于 Anthropic 模型，请使用你的 Anthropic API key。
+
+## 快速开始
+
+1. 设置提供商 API key 和 Gateway 详细信息：
+
+```bash
+quantumclaw onboard --auth-choice cloudflare-ai-gateway-api-key
+```
+
+2. 设置默认模型：
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "cloudflare-ai-gateway/claude-sonnet-4-5" },
+    },
+  },
+}
+```
+
+## 非交互式示例
+
+```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"
+```
+
+## 已认证的 Gateway
+
+如果你在 Cloudflare 中启用了 Gateway 认证，请添加 `cf-aig-authorization` header（这是在你的提供商 API key 之外额外添加的）。
+
+```json5
+{
+  models: {
+    providers: {
+      "cloudflare-ai-gateway": {
+        headers: {
+          "cf-aig-authorization": "Bearer <cloudflare-ai-gateway-token>",
+        },
+      },
+    },
+  },
+}
+```
+
+## 环境说明
+
+如果 Gateway 作为守护进程运行（launchd/systemd），请确保 `CLOUDFLARE_AI_GATEWAY_API_KEY` 对该进程可用（例如放在 `~/.quantumclaw/.env` 中，或通过 `env.shellEnv` 提供）。