配额回退¶

当观察者的提供商无法提供服务时（其配额已耗尽、在重试后仍处于限流或过载状态、宕机，或持续返回无可用的输出），claude-mem 会将其置于短暂冷却中并停止向其发送任务，以免反复触发相同的拒绝。

默认情况下，在提供商被持有的期间，这些任务会转移到你的 Anthropic 套餐（Claude），前提是 Claude 能在这台机器上运行（需要 Claude Code 登录，或在 ~/.claude-mem/.env 中配置 ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN）。冷却结束后，一个生成器会探测原始提供商；如果它响应了，所有任务会自动移回。如果 Claude 无法运行，或者你关闭了回退功能，任务会等待并保持排队状态，直到提供商恢复。

这适用于你选择的提供商是 claude-mem 观察者（cmem.ai）、OpenRouter、Gemini、Codex 或 OpenAI 兼容端点的情况。当 Claude 是你选择的提供商时，它还可以在其两个凭证之间切换——API 密钥和你的 Claude Code 登录：请参阅 Claude 凭证回退。

设置¶

将这些添加到 ~/.claude-mem/settings.json，或在查看器中通过 设置 → 高级 进行设置：

例如，Gemini 作为主要提供商，Claude Haiku 作为回退：

{
  "CLAUDE_MEM_PROVIDER": "gemini",
  "CLAUDE_MEM_QUOTA_FALLBACK_PROVIDER": "claude",
  "CLAUDE_MEM_QUOTA_FALLBACK_MODEL": "claude-haiku-4-5-20251001"
}

要关闭回退：

{
  "CLAUDE_MEM_QUOTA_FALLBACK_PROVIDER": "off"
}

早期版本的设置文件对此设置持有 ""；现在这表示默认值，因此这些安装也会获得 Anthropic 套餐回退。只有 off 表示选择退出。

回退需要自己的凭证：Gemini、OpenRouter 或 OpenAI 兼容 API 密钥，或用于 Claude 的 Claude Code 登录（或 Anthropic 密钥）。没有凭证的回退，或任何自身被持有（配额冷却或密钥被拒）的回退，都会被跳过，任务会像没有回退一样等待。对于 Claude，claude-mem 会检查登录或密钥是否存在；已过期的登录会在首次回退运行时失败，然后被跳过，直到你重新登录。当 cmem.ai 网关将你的账户拒之门外（套餐过期、配额耗尽）时，它作为回退会被跳过 15 分钟，然后由单个请求重新尝试；下次会话开始时会用网关自己的原话告诉你一次。网关上的无人值守重试无论是作为你的提供商还是回退，都按相同方式限制。

什么会切换，什么不会¶

• 会切换： 配额耗尽（30 分钟冷却）；在提供商自身重试后仍被拒绝的限流和"过载"拒绝；超过重试时长仍未恢复的故障（5xx、网络错误、超时）；以及提供商对同一批次两次返回而无可用输出——此时该批次会交给回退而不是丢弃（各 90 秒冷却）。冷却结束且原始提供商响应探测后，任务会立即移回。
• claude-mem 观察者（cmem.ai）拒绝你的密钥（试用或套餐过期）也会将记忆转移到你的 Anthropic 套餐，并每 15 分钟重新检查一次观察者。
• 不会切换： 其他提供商的认证错误——无效、过期或被撤销的密钥（401/403）。这些会像以前一样暂停采集，因为换一个提供商也无法修复密钥问题。
• 密钥有问题的回退在被拒绝后会被跳过。 只有缺失的密钥会被提前检测到；无效或被撤销的回退密钥会在首次运行时失败，其认证冷却随后将其移出轮换。请修复或清除回退密钥。
• 暂停的任务会自动恢复。 因配额错误而停止的生成器会保留其排队的观察任务。Worker 的定期恢复（每分钟一次）会在任何能接手的提供商上重启这些任务——回退，或如果届时已恢复则回到原始提供商——会话的下一次工具调用也会更早地执行相同操作。如果两者都无法接手，则照旧等待。
• 两者都耗尽： 如果回退也处于配额冷却中，则不会有任何变化：任务会等待，直到其中一方解除。

Claude 凭证回退¶

Claude 观察者使用以下两个凭证之一计费：~/.claude-mem/.env 中的 ANTHROPIC_API_KEY（如果设置了），否则使用你的 Claude Code 登录。当该凭证因配额被持有时，CLAUDE_MEM_QUOTA_FALLBACK_AUTH_METHOD 指定在此期间运行的另一个凭证：

例如，为了保护你的套餐，并在配额保护暂停后在 API 额度上消费：

# ~/.claude-mem/.env
ANTHROPIC_FALLBACK_API_KEY=sk-ant-...

{
  "CLAUDE_MEM_QUOTA_FALLBACK_AUTH_METHOD": "api-key"
}

• 会切换： 配额耗尽（额度余额过低、套餐限制），以及对于登录，配额保护在其 CLAUDE_MEM_QUOTA_THRESHOLD_* 限制下触发的暂停。故障、限流和认证错误不会切换：同一个 API 服务于两个凭证，被拒绝的凭证需要你采取行动。
• 顺序： 先尝试另一个凭证，然后当两者都被持有时尝试 CLAUDE_MEM_QUOTA_FALLBACK_PROVIDER，最后暂停采集。
• 如何结束： 30 分钟冷却结束后，一个生成器会探测主要凭证。如果它响应了，所有会话都会切回。如果没有，冷却会重新启用，回退凭证继续运行。
• 花费什么： subscription 运行计入你交互使用的套餐，因此配额保护仍会在接近其限制时暂停它们。api-key 运行按请求计费且无人监控；请在 Anthropic Console 中为密钥的工作区设置消费限制。
• 网关： 这两个值在 ANTHROPIC_BASE_URL 下均不适用，因此观察者流量永远不会绕过你配置的网关。
• 日志会显示一次切换：API key quota exhausted; running the Claude observer on the subscription login until the key recovers（API 密钥配额耗尽；在订阅登录上运行 Claude 观察者，直到密钥恢复），或 Claude Code login paused for quota; running the Claude observer on the fallback API key until the login recovers（Claude Code 登录因配额暂停；在回退 API 密钥上运行 Claude 观察者，直到登录恢复）。会话开始通知会说明记忆正在哪个凭证上运行。

须知事项¶

• 它会消耗备用模型的配额。 当 Claude 作为备用模型时，观察运行会计入你的 Claude 套餐。将 CLAUDE_MEM_QUOTA_FALLBACK_MODEL 设置为 Haiku 模型可保持低成本。
• Claude 运行受 CLAUDE_MEM_MAX_CONCURRENT_AGENTS 限制（默认 2）。当有三个或更多正在运行的会话使用 Claude 备用模型时，额外的会话会等待空位。
• Telegram 总结不受 CLAUDE_MEM_QUOTA_FALLBACK_MODEL 管辖：它们使用会话上次运行时所使用的模型，或摘要层级模型。
• 会话开始通知。 当另一个提供商正在服务时，通知会显示捕获在该提供商处继续进行（对于 Claude：记忆正在你的 Anthropic 套餐上运行），而不是显示记忆已暂停。该通知在每次冷却开始或结束时刷新，因此在更改设置后，它可能会滞后一步。

在 worker 日志中，切换显示为 Primary cannot serve right now; memory runs on the Anthropic plan (Claude) until it recovers（或使用另一种备用模型时显示 Primary in quota cooldown; dispatching to fallback），稍后会出现 Primary quota cooldown elapsed; probing primary 和 Primary recovered from quota cooldown。如果没有任何一方能接手工作，日志会说明一次：Primary and fallback both in quota cooldown; … 或 Primary in quota cooldown and the quota fallback cannot serve; …。