@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/concepts/memory.md

@@ -0,0 +1,412 @@
+---
+read_when:
+  - 你想了解记忆文件布局和工作流程
+  - 你想调整自动压缩前的记忆刷新
+summary: QuantumClaw 记忆的工作原理（工作空间文件 + 自动记忆刷新）
+title: 记忆
+x-i18n:
+  generated_at: "2026-02-03T07:47:38Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: f3a7f5d9f61f9742eb3a8adbc3ccaddeadb7e48ceccdfb595327d6d1f55cd00e
+  source_path: concepts/memory.md
+  workflow: 15
+---
+
+# 记忆
+
+QuantumClaw 记忆是**智能体工作空间中的纯 Markdown 文件**。这些文件是唯一的事实来源；模型只"记住"写入磁盘的内容。
+
+记忆搜索工具由活动的记忆插件提供（默认：`memory-core`）。使用 `plugins.slots.memory = "none"` 禁用记忆插件。
+
+## 记忆文件（Markdown）
+
+默认工作空间布局使用两个记忆层：
+
+- `memory/YYYY-MM-DD.md`
+  - 每日日志（仅追加）。
+  - 在会话开始时读取今天和昨天的内容。
+- `MEMORY.md`（可选）
+  - 精心整理的长期记忆。
+  - **仅在主要的私人会话中加载**（绝不在群组上下文中加载）。
+
+这些文件位于工作空间下（`agents.defaults.workspace`，默认 `~/.quantumclaw/workspace`）。完整布局参见[智能体工作空间](/concepts/agent-workspace)。
+
+## 何时写入记忆
+
+- 决策、偏好和持久性事实写入 `MEMORY.md`。
+- 日常笔记和运行上下文写入 `memory/YYYY-MM-DD.md`。
+- 如果有人说"记住这个"，就写下来（不要只保存在内存中）。
+- 这个领域仍在发展中。提醒模型存储记忆会有帮助；它会知道该怎么做。
+- 如果你想让某些内容持久保存，**请要求机器人将其写入**记忆。
+
+## 自动记忆刷新（压缩前触发）
+
+当会话**接近自动压缩**时，QuantumClaw 会触发一个**静默的智能体回合**，提醒模型在上下文被压缩**之前**写入持久记忆。默认提示明确说明模型*可以回复*，但通常 `NO_REPLY` 是正确的响应，因此用户永远不会看到这个回合。
+
+这由 `agents.defaults.compaction.memoryFlush` 控制：
+
+```json5
+{
+  agents: {
+    defaults: {
+      compaction: {
+        reserveTokensFloor: 20000,
+        memoryFlush: {
+          enabled: true,
+          softThresholdTokens: 4000,
+          systemPrompt: "Session nearing compaction. Store durable memories now.",
+          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store.",
+        },
+      },
+    },
+  },
+}
+```
+
+详情：
+
+- **软阈值**：当会话 token 估计超过 `contextWindow - reserveTokensFloor - softThresholdTokens` 时触发刷新。
+- 默认**静默**：提示包含 `NO_REPLY`，因此不会发送任何内容。
+- **两个提示**：一个用户提示加一个系统提示附加提醒。
+- **每个压缩周期刷新一次**（在 `sessions.json` 中跟踪）。
+- **工作空间必须可写**：如果会话以 `workspaceAccess: "ro"` 或 `"none"` 在沙箱中运行，则跳过刷新。
+
+完整的压缩生命周期参见[会话管理 + 压缩](/reference/session-management-compaction)。
+
+## 向量记忆搜索
+
+QuantumClaw 可以在 `MEMORY.md` 和 `memory/*.md`（以及你选择加入的任何额外目录或文件）上构建小型向量索引，以便语义查询可以找到相关笔记，即使措辞不同。
+
+默认值：
+
+- 默认启用。
+- 监视记忆文件的更改（去抖动）。
+- 默认使用远程嵌入。如果未设置 `memorySearch.provider`，QuantumClaw 自动选择：
+  1. 如果配置了 `memorySearch.local.modelPath` 且文件存在，则使用 `local`。
+  2. 如果可以解析 OpenAI 密钥，则使用 `openai`。
+  3. 如果可以解析 Gemini 密钥，则使用 `gemini`。
+  4. 否则记忆搜索保持禁用状态直到配置完成。
+- 本地模式使用 node-llama-cpp，可能需要运行 `pnpm approve-builds`。
+- 使用 sqlite-vec（如果可用）在 SQLite 中加速向量搜索。
+
+远程嵌入**需要**嵌入提供商的 API 密钥。QuantumClaw 从身份验证配置文件、`models.providers.*.apiKey` 或环境变量解析密钥。Codex OAuth 仅涵盖聊天/补全，**不**满足记忆搜索的嵌入需求。对于 Gemini，使用 `GEMINI_API_KEY` 或 `models.providers.google.apiKey`。使用自定义 OpenAI 兼容端点时，设置 `memorySearch.remote.apiKey`（以及可选的 `memorySearch.remote.headers`）。
+
+### 额外记忆路径
+
+如果你想索引默认工作空间布局之外的 Markdown 文件，添加显式路径：
+
+```json5
+agents: {
+  defaults: {
+    memorySearch: {
+      extraPaths: ["../team-docs", "/srv/shared-notes/overview.md"]
+    }
+  }
+}
+```
+
+说明：
+
+- 路径可以是绝对路径或工作空间相对路径。
+- 目录会递归扫描 `.md` 文件。
+- 仅索引 Markdown 文件。
+- 符号链接被忽略（文件或目录）。
+
+### Gemini 嵌入（原生）
+
+将提供商设置为 `gemini` 以直接使用 Gemini 嵌入 API：
+
+```json5
+agents: {
+  defaults: {
+    memorySearch: {
+      provider: "gemini",
+      model: "gemini-embedding-001",
+      remote: {
+        apiKey: "YOUR_GEMINI_API_KEY"
+      }
+    }
+  }
+}
+```
+
+说明：
+
+- `remote.baseUrl` 是可选的（默认为 Gemini API 基础 URL）。
+- `remote.headers` 让你可以在需要时添加额外的标头。
+- 默认模型：`gemini-embedding-001`。
+
+如果你想使用**自定义 OpenAI 兼容端点**（OpenRouter、vLLM 或代理），可以使用 `remote` 配置与 OpenAI 提供商：
+
+```json5
+agents: {
+  defaults: {
+    memorySearch: {
+      provider: "openai",
+      model: "text-embedding-3-small",
+      remote: {
+        baseUrl: "https://api.example.com/v1/",
+        apiKey: "YOUR_OPENAI_COMPAT_API_KEY",
+        headers: { "X-Custom-Header": "value" }
+      }
+    }
+  }
+}
+```
+
+如果你不想设置 API 密钥，使用 `memorySearch.provider = "local"` 或设置 `memorySearch.fallback = "none"`。
+
+回退：
+
+- `memorySearch.fallback` 可以是 `openai`、`gemini`、`local` 或 `none`。
+- 回退提供商仅在主嵌入提供商失败时使用。
+
+批量索引（OpenAI + Gemini）：
+
+- OpenAI 和 Gemini 嵌入默认启用。设置 `agents.defaults.memorySearch.remote.batch.enabled = false` 以禁用。
+- 默认行为等待批处理完成；如果需要可以调整 `remote.batch.wait`、`remote.batch.pollIntervalMs` 和 `remote.batch.timeoutMinutes`。
+- 设置 `remote.batch.concurrency` 以控制我们并行提交多少个批处理作业（默认：2）。
+- 批处理模式在 `memorySearch.provider = "openai"` 或 `"gemini"` 时适用，并使用相应的 API 密钥。
+- Gemini 批处理作业使用异步嵌入批处理端点，需要 Gemini Batch API 可用。
+
+为什么 OpenAI 批处理快速又便宜：
+
+- 对于大型回填，OpenAI 通常是我们支持的最快选项，因为我们可以在单个批处理作业中提交许多嵌入请求，让 OpenAI 异步处理它们。
+- OpenAI 为 Batch API 工作负载提供折扣定价，因此大型索引运行通常比同步发送相同请求更便宜。
+- 详情参见 OpenAI Batch API 文档和定价：
+  - https://platform.openai.com/docs/api-reference/batch
+  - https://platform.openai.com/pricing
+
+配置示例：
+
+```json5
+agents: {
+  defaults: {
+    memorySearch: {
+      provider: "openai",
+      model: "text-embedding-3-small",
+      fallback: "openai",
+      remote: {
+        batch: { enabled: true, concurrency: 2 }
+      },
+      sync: { watch: true }
+    }
+  }
+}
+```
+
+工具：
+
+- `memory_search` — 返回带有文件 + 行范围的片段。
+- `memory_get` — 按路径读取记忆文件内容。
+
+本地模式：
+
+- 设置 `agents.defaults.memorySearch.provider = "local"`。
+- 提供 `agents.defaults.memorySearch.local.modelPath`（GGUF 或 `hf:` URI）。
+- 可选：设置 `agents.defaults.memorySearch.fallback = "none"` 以避免远程回退。
+
+### 记忆工具的工作原理
+
+- `memory_search` 从 `MEMORY.md` + `memory/**/*.md` 语义搜索 Markdown 块（目标约 400 个 token，80 个 token 重叠）。它返回片段文本（上限约 700 个字符）、文件路径、行范围、分数、提供商/模型，以及我们是否从本地回退到远程嵌入。不返回完整文件内容。
+- `memory_get` 读取特定的记忆 Markdown 文件（工作空间相对路径），可选从起始行开始读取 N 行。`MEMORY.md` / `memory/` 之外的路径仅在明确列在 `memorySearch.extraPaths` 中时才允许。
+- 两个工具仅在智能体的 `memorySearch.enabled` 解析为 true 时启用。
+
+### 索引内容（及时机）
+
+- 文件类型：仅 Markdown（`MEMORY.md`、`memory/**/*.md`，以及 `memorySearch.extraPaths` 下的任何 `.md` 文件）。
+- 索引存储：每个智能体的 SQLite 位于 `~/.quantumclaw/memory/<agentId>.sqlite`（可通过 `agents.defaults.memorySearch.store.path` 配置，支持 `{agentId}` 令牌）。
+- 新鲜度：监视器监视 `MEMORY.md`、`memory/` 和 `memorySearch.extraPaths`，标记索引为脏（去抖动 1.5 秒）。同步在会话开始时、搜索时或按间隔安排，并异步运行。会话记录使用增量阈值触发后台同步。
+- 重新索引触发器：索引存储嵌入的**提供商/模型 + 端点指纹 + 分块参数**。如果其中任何一个发生变化，QuantumClaw 会自动重置并重新索引整个存储。
+
+### 混合搜索（BM25 + 向量）
+
+启用时，QuantumClaw 结合：
+
+- **向量相似度**（语义匹配，措辞可以不同）
+- **BM25 关键词相关性**（精确令牌如 ID、环境变量、代码符号）
+
+如果你的平台上全文搜索不可用，QuantumClaw 会回退到纯向量搜索。
+
+#### 为什么使用混合搜索？
+
+向量搜索擅长"这意味着同一件事"：
+
+- "Mac Studio gateway host" vs "运行 gateway 的机器"
+- "debounce file updates" vs "避免每次写入都索引"
+
+但它在精确的高信号令牌上可能较弱：
+
+- ID（`a828e60`、`b3b9895a…`）
+- 代码符号（`memorySearch.query.hybrid`）
+- 错误字符串（"sqlite-vec unavailable"）
+
+BM25（全文）正好相反：擅长精确令牌，弱于释义。
+混合搜索是务实的中间地带：**同时使用两种检索信号**，这样你可以在"自然语言"查询和"大海捞针"查询上都获得好结果。
+
+#### 我们如何合并结果（当前设计）
+
+实现概述：
+
+1. 从双方检索候选池：
+
+- **向量**：按余弦相似度取前 `maxResults * candidateMultiplier` 个。
+- **BM25**：按 FTS5 BM25 排名取前 `maxResults * candidateMultiplier` 个（越低越好）。
+
+2. 将 BM25 排名转换为 0..1 范围的分数：
+
+- `textScore = 1 / (1 + max(0, bm25Rank))`
+
+3. 按块 id 合并候选并计算加权分数：
+
+- `finalScore = vectorWeight * vectorScore + textWeight * textScore`
+
+说明：
+
+- 在配置解析中 `vectorWeight` + `textWeight` 归一化为 1.0，因此权重表现为百分比。
+- 如果嵌入不可用（或提供商返回零向量），我们仍然运行 BM25 并返回关键词匹配。
+- 如果无法创建 FTS5，我们保持纯向量搜索（不会硬失败）。
+
+这不是"IR 理论完美"的，但它简单、快速，并且往往能提高真实笔记的召回率/精确率。
+如果我们以后想要更复杂的方案，常见的下一步是倒数排名融合（RRF）或在混合之前进行分数归一化（最小/最大或 z 分数）。
+
+配置：
+
+```json5
+agents: {
+  defaults: {
+    memorySearch: {
+      query: {
+        hybrid: {
+          enabled: true,
+          vectorWeight: 0.7,
+          textWeight: 0.3,
+          candidateMultiplier: 4
+        }
+      }
+    }
+  }
+}
+```
+
+### 嵌入缓存
+
+QuantumClaw 可以在 SQLite 中缓存**块嵌入**，这样重新索引和频繁更新（特别是会话记录）不会重新嵌入未更改的文本。
+
+配置：
+
+```json5
+agents: {
+  defaults: {
+    memorySearch: {
+      cache: {
+        enabled: true,
+        maxEntries: 50000
+      }
+    }
+  }
+}
+```
+
+### 会话记忆搜索（实验性）
+
+你可以选择性地索引**会话记录**并通过 `memory_search` 呈现它们。
+这由实验性标志控制。
+
+```json5
+agents: {
+  defaults: {
+    memorySearch: {
+      experimental: { sessionMemory: true },
+      sources: ["memory", "sessions"]
+    }
+  }
+}
+```
+
+说明：
+
+- 会话索引是**选择加入**的（默认关闭）。
+- 会话更新被去抖动并在超过增量阈值后**异步索引**（尽力而为）。
+- `memory_search` 永远不会阻塞索引；在后台同步完成之前，结果可能略有延迟。
+- 结果仍然只包含片段；`memory_get` 仍然仅限于记忆文件。
+- 会话索引按智能体隔离（仅索引该智能体的会话日志）。
+- 会话日志存储在磁盘上（`~/.quantumclaw/agents/<agentId>/sessions/*.jsonl`）。任何具有文件系统访问权限的进程/用户都可以读取它们，因此将磁盘访问视为信任边界。对于更严格的隔离，在单独的操作系统用户或主机下运行智能体。
+
+增量阈值（显示默认值）：
+
+```json5
+agents: {
+  defaults: {
+    memorySearch: {
+      sync: {
+        sessions: {
+          deltaBytes: 100000,   // ~100 KB
+          deltaMessages: 50     // JSONL 行数
+        }
+      }
+    }
+  }
+}
+```
+
+### SQLite 向量加速（sqlite-vec）
+
+当 sqlite-vec 扩展可用时，QuantumClaw 将嵌入存储在 SQLite 虚拟表（`vec0`）中，并在数据库中执行向量距离查询。这使搜索保持快速，无需将每个嵌入加载到 JS 中。
+
+配置（可选）：
+
+```json5
+agents: {
+  defaults: {
+    memorySearch: {
+      store: {
+        vector: {
+          enabled: true,
+          extensionPath: "/path/to/sqlite-vec"
+        }
+      }
+    }
+  }
+}
+```
+
+说明：
+
+- `enabled` 默认为 true；禁用时，搜索回退到对存储嵌入的进程内余弦相似度计算。
+- 如果 sqlite-vec 扩展缺失或加载失败，QuantumClaw 会记录错误并继续使用 JS 回退（无向量表）。
+- `extensionPath` 覆盖捆绑的 sqlite-vec 路径（对于自定义构建或非标准安装位置很有用）。
+
+### 本地嵌入自动下载
+
+- 默认本地嵌入模型：`hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf`（约 0.6 GB）。
+- 当 `memorySearch.provider = "local"` 时，`node-llama-cpp` 解析 `modelPath`；如果 GGUF 缺失，它会**自动下载**到缓存（或 `local.modelCacheDir`，如果已设置），然后加载它。下载在重试时会续传。
+- 原生构建要求：运行 `pnpm approve-builds`，选择 `node-llama-cpp`，然后运行 `pnpm rebuild node-llama-cpp`。
+- 回退：如果本地设置失败且 `memorySearch.fallback = "openai"`，我们自动切换到远程嵌入（`openai/text-embedding-3-small`，除非被覆盖）并记录原因。
+
+### 自定义 OpenAI 兼容端点示例
+
+```json5
+agents: {
+  defaults: {
+    memorySearch: {
+      provider: "openai",
+      model: "text-embedding-3-small",
+      remote: {
+        baseUrl: "https://api.example.com/v1/",
+        apiKey: "YOUR_REMOTE_API_KEY",
+        headers: {
+          "X-Organization": "org-id",
+          "X-Project": "project-id"
+        }
+      }
+    }
+  }
+}
+```
+
+说明：
+
+- `remote.*` 优先于 `models.providers.openai.*`。
+- `remote.headers` 与 OpenAI 标头合并；键冲突时 remote 优先。省略 `remote.headers` 以使用 OpenAI 默认值。

package/docs/zh-CN/concepts/messages.md

@@ -0,0 +1,141 @@
+---
+read_when:
+  - 解释入站消息如何转化为回复
+  - 阐明会话、队列模式或流式传输行为
+  - 记录推理可见性和使用影响
+summary: 消息流程、会话、队列和推理可见性
+title: 消息
+x-i18n:
+  generated_at: "2026-02-03T10:05:22Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 147362b61bee21ee6e303654d970a052325f076ddb45814306053f70409737b5
+  source_path: concepts/messages.md
+  workflow: 15
+---
+
+# 消息
+
+本页汇总了 QuantumClaw 如何处理入站消息、会话、队列、流式传输和推理可见性。
+
+## 消息流程（高层概述）
+
+```
+入站消息
+  -> 路由/绑定 -> 会话密钥
+  -> 队列（如果有运行中的任务）
+  -> 智能体运行（流式传输 + 工具）
+  -> 出站回复（渠道限制 + 分块）
+```
+
+关键配置项在配置中：
+
+- `messages.*` 用于前缀、队列和群组行为。
+- `agents.defaults.*` 用于分块流式传输和分块默认值。
+- 渠道覆盖（`channels.whatsapp.*`、`channels.telegram.*` 等）用于上限和流式传输开关。
+
+完整 schema 参见[配置](/gateway/configuration)。
+
+## 入站去重
+
+渠道可能在重新连接后重复投递同一消息。QuantumClaw 保持一个短期缓存，以渠道/账户/对端/会话/消息 ID 为键，因此重复投递不会触发另一次智能体运行。
+
+## 入站防抖
+
+来自**同一发送者**的快速连续消息可以通过 `messages.inbound` 批量合并为单个智能体轮次。防抖按渠道 + 会话为范围，并使用最近的消息进行回复线程/ID 处理。
+
+配置（全局默认 + 单渠道覆盖）：
+
+```json5
+{
+  messages: {
+    inbound: {
+      debounceMs: 2000,
+      byChannel: {
+        whatsapp: 5000,
+        slack: 1500,
+        discord: 1500,
+      },
+    },
+  },
+}
+```
+
+注意事项：
+
+- 防抖仅适用于**纯文本**消息；媒体/附件会立即刷新。
+- 控制命令会绕过防抖，保持独立。
+
+## 会话和设备
+
+会话由 Gateway 网关拥有，而非客户端。
+
+- 直接聊天合并到智能体主会话密钥。
+- 群组/渠道获得各自的会话密钥。
+- 会话存储和记录保存在 Gateway 网关主机上。
+
+多个设备/渠道可以映射到同一会话，但历史记录不会完全同步回每个客户端。建议：对长对话使用一个主设备，以避免上下文分歧。控制 UI 和 TUI 始终显示 Gateway 网关支持的会话记录，因此它们是事实来源。
+
+详情：[会话管理](/concepts/session)。
+
+## 入站正文和历史上下文
+
+QuantumClaw 将**提示正文**与**命令正文**分开：
+
+- `Body`：发送给智能体的提示文本。这可能包括渠道信封和可选的历史包装器。
+- `CommandBody`：用于指令/命令解析的原始用户文本。
+- `RawBody`：`CommandBody` 的旧别名（为兼容性保留）。
+
+当渠道提供历史记录时，使用共享包装器：
+
+- `[Chat messages since your last reply - for context]`
+- `[Current message - respond to this]`
+
+对于**非直接聊天**（群组/渠道/房间），**当前消息正文**会加上发送者标签前缀（与历史条目使用的样式相同）。这使智能体提示中的实时消息和队列/历史消息保持一致。
+
+历史缓冲区是**仅待处理的**：它们包含*未*触发运行的群组消息（例如，提及门控的消息），并**排除**已在会话记录中的消息。
+
+指令剥离仅适用于**当前消息**部分，因此历史记录保持完整。包装历史记录的渠道应将 `CommandBody`（或 `RawBody`）设置为原始消息文本，并将 `Body` 保留为组合提示。历史缓冲区可通过 `messages.groupChat.historyLimit`（全局默认）和单渠道覆盖（如 `channels.slack.historyLimit` 或 `channels.telegram.accounts.<id>.historyLimit`）进行配置（设置 `0` 表示禁用）。
+
+## 队列和后续消息
+
+如果运行已在进行中，入站消息可以排队、导入当前运行，或收集用于后续轮次。
+
+- 通过 `messages.queue`（和 `messages.queue.byChannel`）配置。
+- 模式：`interrupt`、`steer`、`followup`、`collect`，以及积压变体。
+
+详情：[队列](/concepts/queue)。
+
+## 流式传输、分块和批处理
+
+分块流式传输在模型生成文本块时发送部分回复。分块遵循渠道文本限制，避免拆分围栏代码。
+
+关键设置：
+
+- `agents.defaults.blockStreamingDefault`（`on|off`，默认 off）
+- `agents.defaults.blockStreamingBreak`（`text_end|message_end`）
+- `agents.defaults.blockStreamingChunk`（`minChars|maxChars|breakPreference`）
+- `agents.defaults.blockStreamingCoalesce`（基于空闲的批处理）
+- `agents.defaults.humanDelay`（块回复之间的拟人化暂停）
+- 渠道覆盖：`*.blockStreaming` 和 `*.blockStreamingCoalesce`（非 Telegram 渠道需要显式设置 `*.blockStreaming: true`）
+
+详情：[流式传输 + 分块](/concepts/streaming)。
+
+## 推理可见性和 token
+
+QuantumClaw 可以显示或隐藏模型推理：
+
+- `/reasoning on|off|stream` 控制可见性。
+- 当模型产生推理内容时，它仍计入 token 使用量。
+- Telegram 支持将推理流式传输到草稿气泡中。
+
+详情：[思考 + 推理指令](/tools/thinking)和 [Token 使用](/reference/token-use)。
+
+## 前缀、线程和回复
+
+出站消息格式在 `messages` 中集中配置：
+
+- `messages.responsePrefix`（出站前缀）和 `channels.whatsapp.messagePrefix`（WhatsApp 入站前缀）
+- 通过 `replyToMode` 和单渠道默认值进行回复线程
+
+详情：[配置](/gateway/configuration#messages)和渠道文档。

package/docs/zh-CN/concepts/model-failover.md

@@ -0,0 +1,145 @@
+---
+read_when:
+  - 诊断认证配置文件轮换、冷却时间或模型回退行为
+  - 更新认证配置文件或模型的故障转移规则
+summary: QuantumClaw 如何轮换认证配置文件并在模型之间进行回退
+title: 模型故障转移
+x-i18n:
+  generated_at: "2026-02-03T07:46:17Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: eab7c0633824d941cf0d6ce4294f0bc8747fbba2ce93650e9643eca327cd04a9
+  source_path: concepts/model-failover.md
+  workflow: 15
+---
+
+# 模型故障转移
+
+QuantumClaw 分两个阶段处理故障：
+
+1. 在当前提供商内进行**认证配置文件轮换**。
+2. **模型回退**到 `agents.defaults.model.fallbacks` 中的下一个模型。
+
+本文档解释运行时规则及其背后的数据。
+
+## 认证存储（密钥 + OAuth）
+
+QuantumClaw 对 API 密钥和 OAuth 令牌都使用**认证配置文件**。
+
+- 密钥存储在 `~/.quantumclaw/agents/<agentId>/agent/auth-profiles.json`（旧版：`~/.quantumclaw/agent/auth-profiles.json`）。
+- 配置 `auth.profiles` / `auth.order` **仅用于元数据和路由**（不含密钥）。
+- 旧版仅导入 OAuth 文件：`~/.quantumclaw/credentials/oauth.json`（首次使用时导入到 `auth-profiles.json`）。
+
+更多详情：[/concepts/oauth](/concepts/oauth)
+
+凭证类型：
+
+- `type: "api_key"` → `{ provider, key }`
+- `type: "oauth"` → `{ provider, access, refresh, expires, email? }`（某些提供商还有 `projectId`/`enterpriseUrl`）
+
+## 配置文件 ID
+
+OAuth 登录创建不同的配置文件，以便多个账户可以共存。
+
+- 默认：当没有电子邮件可用时为 `provider:default`。
+- 带电子邮件的 OAuth：`provider:<email>`（例如 `google-antigravity:user@gmail.com`）。
+
+配置文件存储在 `~/.quantumclaw/agents/<agentId>/agent/auth-profiles.json` 的 `profiles` 下。
+
+## 轮换顺序
+
+当一个提供商有多个配置文件时，QuantumClaw 按以下顺序选择：
+
+1. **显式配置**：`auth.order[provider]`（如果设置）。
+2. **已配置的配置文件**：按提供商过滤的 `auth.profiles`。
+3. **已存储的配置文件**：`auth-profiles.json` 中该提供商的条目。
+
+如果没有配置显式顺序，QuantumClaw 使用轮询顺序：
+
+- **主键：** 配置文件类型（**OAuth 优先于 API 密钥**）。
+- **次键：** `usageStats.lastUsed`（每种类型中最旧的优先）。
+- **冷却/禁用的配置文件**会移到末尾，按最早过期时间排序。
+
+### 会话粘性（缓存友好）
+
+QuantumClaw **为每个会话固定所选的认证配置文件**以保持提供商缓存热度。它**不会**在每个请求时轮换。固定的配置文件会被重用直到：
+
+- 会话被重置（`/new` / `/reset`）
+- 压缩完成（压缩计数递增）
+- 配置文件处于冷却/禁用状态
+
+通过 `/model …@<profileId>` 手动选择会为该会话设置**用户覆盖**，在新会话开始之前不会自动轮换。
+
+自动固定的配置文件（由会话路由器选择）被视为**偏好**：它们会优先尝试，但 QuantumClaw 可能在速率限制/超时时轮换到另一个配置文件。用户固定的配置文件会锁定到该配置文件；如果失败且配置了模型回退，QuantumClaw 会移动到下一个模型而不是切换配置文件。
+
+### 为什么 OAuth 可能"看起来丢失"
+
+如果你为同一个提供商同时拥有 OAuth 配置文件和 API 密钥配置文件，除非固定，否则轮询可能在消息之间切换它们。要强制使用单个配置文件：
+
+- 使用 `auth.order[provider] = ["provider:profileId"]` 固定，或
+- 通过 `/model …` 使用每会话覆盖并指定配置文件覆盖（当你的 UI/聊天界面支持时）。
+
+## 冷却时间
+
+当配置文件因认证/速率限制错误（或看起来像速率限制的超时）而失败时，QuantumClaw 将其标记为冷却状态并移动到下一个配置文件。格式/无效请求错误（例如 Cloud Code Assist 工具调用 ID 验证失败）被视为值得故障转移的情况，使用相同的冷却时间。
+
+冷却时间使用指数退避：
+
+- 1 分钟
+- 5 分钟
+- 25 分钟
+- 1 小时（上限）
+
+状态存储在 `auth-profiles.json` 的 `usageStats` 下：
+
+```json
+{
+  "usageStats": {
+    "provider:profile": {
+      "lastUsed": 1736160000000,
+      "cooldownUntil": 1736160600000,
+      "errorCount": 2
+    }
+  }
+}
+```
+
+## 账单禁用
+
+账单/额度失败（例如"insufficient credits"/"credit balance too low"）被视为值得故障转移的情况，但它们通常不是暂时性的。QuantumClaw 不使用短冷却时间，而是将配置文件标记为**禁用**（使用更长的退避时间）并轮换到下一个配置文件/提供商。
+
+状态存储在 `auth-profiles.json` 中：
+
+```json
+{
+  "usageStats": {
+    "provider:profile": {
+      "disabledUntil": 1736178000000,
+      "disabledReason": "billing"
+    }
+  }
+}
+```
+
+默认值：
+
+- 账单退避从 **5 小时**开始，每次账单失败翻倍，上限为 **24 小时**。
+- 如果配置文件 **24 小时**内没有失败，退避计数器会重置（可配置）。
+
+## 模型回退
+
+如果某个提供商的所有配置文件都失败，QuantumClaw 会移动到 `agents.defaults.model.fallbacks` 中的下一个模型。这适用于认证失败、速率限制和耗尽配置文件轮换的超时（其他错误不会推进回退）。
+
+当运行以模型覆盖（钩子或 CLI）开始时，在尝试任何配置的回退之后，回退仍会在 `agents.defaults.model.primary` 处结束。
+
+## 相关配置
+
+参阅 [Gateway 网关配置](/gateway/configuration) 了解：
+
+- `auth.profiles` / `auth.order`
+- `auth.cooldowns.billingBackoffHours` / `auth.cooldowns.billingBackoffHoursByProvider`
+- `auth.cooldowns.billingMaxHours` / `auth.cooldowns.failureWindowHours`
+- `agents.defaults.model.primary` / `agents.defaults.model.fallbacks`
+- `agents.defaults.imageModel` 路由
+
+参阅[模型](/concepts/models)了解更广泛的模型选择和回退概述。