多密钥轮换¶

为某个提供商分配多个 API 密钥后，claude-mem 会在它们之间轮换使用：当某个密钥触发速率限制、耗尽配额或被发现无效时，它会被暂时搁置进入冷却期，下一次请求则使用下一个密钥。

它能解决什么问题¶

如果没有密钥池，单个密钥的耗尽会让记忆功能在剩余时间窗口内停止：

• rate_limit 会针对同一个密钥再重试两次，遵循默认 60 秒的 Retry-After——因此每次观察都会停滞整整一分钟，然后仍然失败。
• quota_exhausted 和 auth_invalid 完全不可重试。生成器直接退出，提供商的配额熔断器会将整个提供商关闭 30 分钟。

配置¶

在现有的单密钥设置旁边添加复数形式的设置。密钥可以用换行符、逗号或空格分隔。

{
  "CLAUDE_MEM_PROVIDER": "gemini",
  "CLAUDE_MEM_GEMINI_API_KEY": "AIza...primary",
  "CLAUDE_MEM_GEMINI_API_KEYS": "AIza...second\nAIza...third"
}

每个复数形式的设置也可以从 ~/.claude-mem/.env 中以 GEMINI_API_KEYS、OPENROUTER_API_KEYS 或 OPENAI_COMPAT_API_KEYS 的形式读取，这样密钥就不会出现在 settings.json 中。

单密钥始终排在轮换池的第一位。你也可以将其留空，通过列表提供所有密钥——列表中的第一个密钥会被提升，因此可用性检查和错误消息照常工作。

轮换如何运作¶

在以下情况下轮换：rate_limit、quota_exhausted、auth_invalid——这三种分类意味着当前密钥存在问题。

在以下情况下不轮换：transient（网络抖动、5xx）或 unrecoverable（格式错误的请求、错误的模型 ID）。重试机制已经处理了前者，而后者在每个密钥上都会以相同方式失败——轮换只会白白消耗密钥池。

冷却窗口

一次成功会立即清除该密钥的冷却状态，因此恢复永远不需要等待整个窗口结束。修正输错的密钥也会立即生效。

当所有密钥都在冷却时，claude-mem 仍会尝试最接近过期时刻的那个，而不是不发送任何请求就直接失败——错误分类，或端点比它公告的更早重置，都不应成为硬性停止。如果那次尝试也失败了，最后分类的错误会原样传播，因此现有的暂停和熔断行为与之前完全一致。

冷却状态会写入 ~/.claude-mem/api-key-cooldown.json，以便在 worker 重启后仍然保留。密钥绝不会写入该文件或任何日志行——两者都使用加盐指纹，在您的安装环境之外毫无意义。

不变的部分¶

• 单个密钥的行为与之前完全相同。 只有一个密钥的池是直通的：相同的请求路径、相同的错误、无冷却记录。
• 提供商选择不受影响。 轮换发生在您所选提供商的内部。当密钥池完全耗尽时，claude-mem 不会静默切换到其他提供商。
• 无论哪个提供商指向 cmem.ai 网关，它都永远不会进行轮换。 其密钥由账户发放，因此网关端点只使用一个 cm_pro_ 密钥，绝不会在多个密钥之间轮换。您的个人密钥绝不会发送给它。
• cm_pro_ 密钥绝不会发送到任何其他主机。 同样的规则适用于 Gemini、OpenRouter 和 OpenAI 兼容池：cm_pro_ 密钥，无论是作为单密钥设置还是放在列表中，都会在对 cmem.ai 网关以外的端点发起任何请求之前被丢弃。只持有 cm_pro_ 密钥的 Gemini 配置被视为没有密钥。

验证¶

轮换事件以 warn 级别记录在 worker 日志（~/.claude-mem/logs/worker-YYYY-MM-DD.log）中，包含密钥池位置和密钥指纹——绝不会记录密钥本身：

OpenRouter key 1/3 hit quota_exhausted; rotating to the next key