OpenRouter 提供商¶

Claude-mem 支持将 OpenRouter 作为观察提取的替代提供商。OpenRouter 提供统一 API，可访问来自不同提供商的 100 多种模型，包括 Google、Meta、Mistral、DeepSeek 等。

为什么使用 OpenRouter？¶

• 不占用套餐配额：观察提取绝不会与您的 Claude 套餐用量共享
• 访问 100+ 模型：通过一个 API 从多个提供商提供的模型中选择
• 免费模型选项：多款高质量模型可免费使用
• 错误明确抛出：429、5xx 和网络故障会抛出——使消息保持待处理状态，以便重试
• 支持热切换：无需重启 worker 即可切换提供商
• 多轮对话：跨 API 调用维护完整对话历史

OpenRouter 上的免费模型¶

OpenRouter 积极支持通过提供免费模型来推动 AI 访问的民主化。这些是适合观察提取的生产就绪模型。

精选免费模型¶

免费模型的注意事项¶

• 速率限制：免费模型可能比付费模型有更严格的速率限制
• 可用性：免费容量取决于提供商合作情况和需求
• 退役：OpenRouter 会定期淘汰免费模型 ID。如果默认模型被淘汰，claude-mem 会自动将存储的设置移出该模型。如果您选择的模型被淘汰，observer 会报告“OpenRouter model unavailable”（参见故障排除）
• 排队时间：高峰使用期间，请求可能会短暂排队
• 最大 token 数：大多数免费模型支持 65,536 个完成 token

所有免费模型都支持：

• 工具使用和函数调用
• 温度和采样控制
• 停止序列
• 流式响应

获取 API 密钥¶

1. 前往 OpenRouter
2. 使用 Google、GitHub 或邮箱登录
3. 导航到 API Keys
4. 点击创建密钥
5. 复制并安全存储您的 API 密钥

配置¶

设置项¶

使用设置 UI¶

1. 打开启动时打印的 worker URL
2. 点击齿轮图标打开设置
3. 在 AI 提供商下选择 OpenRouter
4. 输入您的 OpenRouter API 密钥
5. 可选：选择其他模型

设置会立即生效——无需重启。

手动配置¶

编辑 ~/.claude-mem/settings.json：

{
  "CLAUDE_MEM_PROVIDER": "openrouter",
  "CLAUDE_MEM_OPENROUTER_API_KEY": "sk-or-v1-your-key-here",
  "CLAUDE_MEM_OPENROUTER_MODEL": "cohere/north-mini-code:free"
}

模型回退¶

CLAUDE_MEM_OPENROUTER_MODEL 也接受列表形式的模型 ID。第一个是通常使用的模型；其余模型会交给 OpenRouter 原生的 models 回退数组，当前一个模型出错时按顺序依次尝试。

{
  "CLAUDE_MEM_PROVIDER": "openrouter",
  "CLAUDE_MEM_OPENROUTER_API_KEY": "sk-or-v1-your-key-here",
  "CLAUDE_MEM_OPENROUTER_MODEL": [
    "vendor/fast-model:free",
    "vendor/backup-model:free",
    "vendor/paid-model"
  ]
}

逗号或空格分隔的字符串同样适用，因此
"vendor/a, vendor/b" 与包含两个条目的数组含义相同。

回退（Fallbacks）仅发送至 openrouter.ai。自定义的 CLAUDE_MEM_OPENROUTER_BASE_URL 网关使用标准 OpenAI 协议，而该协议没有 models 字段，因此它只会接收第一个 id，并忽略其余部分。

或者，通过环境变量设置 API 密钥：

export OPENROUTER_API_KEY="sk-or-v1-your-key-here"

设置文件的优先级高于环境变量。

自定义 OpenAI 兼容网关¶

OpenRouter provider 是一个通用的 OpenAI 兼容客户端。将 CLAUDE_MEM_OPENROUTER_BASE_URL 设置为任何支持 /chat/completions 的服务器，例如 DeepSeek（https://api.deepseek.com）、LM Studio（http://localhost:1234/v1）或 io.net 的 IO Intelligence。模型 id 会原样发送，回退列表中的第一个 id 会被使用（标准 OpenAI 没有 models 字段）。请使用该端点签发的密钥：claude-mem observer 密钥（cm_pro_…）只会被发送给 claude-mem observer。

例如，IO Intelligence：

{
  "CLAUDE_MEM_PROVIDER": "openrouter",
  "CLAUDE_MEM_OPENROUTER_BASE_URL": "https://api.intelligence.io.solutions/api/v1",
  "CLAUDE_MEM_OPENROUTER_MODEL": "meta-llama/Llama-3.3-70B-Instruct",
  "CLAUDE_MEM_OPENROUTER_API_KEY": "YOUR_IO_INTELLIGENCE_API_KEY"
}

模型 id 是 IO Intelligence 模型列表 中形如 org/name 的 ID，例如 deepseek-ai/DeepSeek-R1-0528 或 zai-org/GLM-4.6。基础 URL 末尾带斜杠是可以的；/chat/completions 会自动追加。

附加请求字段¶

CLAUDE_MEM_OPENROUTER_EXTRA_BODY 将一个 JSON 对象合并到每个请求中，用于补充 claude-mem 自身不会设置的 provider 特有字段。常见场景是推理模型将全部输出预算用于思考，最终什么答案都没有。此时可以关闭其推理功能：

{
  "CLAUDE_MEM_OPENROUTER_EXTRA_BODY": { "reasoning": { "enabled": false } }
}

作为环境变量时，它以字符串形式表示同一个对象：CLAUDE_MEM_OPENROUTER_EXTRA_BODY='{"reasoning":{"enabled":false}}'。自定义网关可以使用其供应商自己的字段代替，例如 {"thinking":{"type":"disabled"}}。

• 值必须是 JSON 对象。其他任何内容都会被忽略，并在 worker 日志中记录警告。
• 它不能替换 model、models、messages、stream、max_tokens 或 max_completion_tokens。这些字段会被丢弃并记录警告。请使用 CLAUDE_MEM_OBSERVER_MAX_OUTPUT_TOKENS 设置输出上限。
• 它绝不会被发送给 claude-mem observer。
• 当设置了 CLAUDE_MEM_OPENROUTER_REASONING_EFFORT 时，该变量负责决定 reasoning，附加请求体中的 reasoning 字段会被忽略。
• 可在 ~/.claude-mem/settings.json 或环境中设置。设置 UI 和 API 不会写入该字段。

模型选择指南¶

免费模型¶

推荐：cohere/north-mini-code:free（默认） - 256K 上下文窗口可处理大型观察结果 - 64K 最大完成令牌数 - 稀疏混合专家架构（3B 活跃参数）

备选方案： - poolside/laguna-xs-2.1:free - 编码 agent 模型，256K 上下文 - nvidia/nemotron-3-ultra-550b-a55b:free - 1M 上下文，推理能力强

高级模型（更高品质/速度）¶

高级模型会消耗您的 OpenRouter 额度——仍然不属于套餐范围，因此绝不会影响您的 Claude 套餐用量。

上下文窗口管理¶

每次请求时，完整的对话历史都会发送给模型。claude-mem 不会应用任何客户端截断或消息数量上限——provider 和模型自行管理各自的上下文窗口。如果您需要为特定模型限制上下文，请选择具有合适上下文长度的模型，或在 OpenRouter/provider 层面管理限制。

用量追踪¶

日志中包含详细的用量信息：

OpenRouter API usage: {
  model: "cohere/north-mini-code:free",
  inputTokens: 2500,
  outputTokens: 1200,
  totalTokens: 3700,
  estimatedCostUSD: "0.00",
  messagesInContext: 8
}

Provider 切换¶

您可以随时切换 provider：

• 无需重启：更改将在下一条观察结果上生效
• 对话历史保留：在会话中途切换时，新 provider 可以看到完整的对话上下文
• 无缝过渡：所有 provider 使用相同的观察结果格式

通过 UI 切换¶

1. 在查看器中打开设置
2. 更改 AI Provider 下拉选项
3. 下一条观察结果将使用新的 provider

通过设置文件切换¶

{
  "CLAUDE_MEM_PROVIDER": "openrouter"
}

错误行为¶

如果 OpenRouter 出错，claude-mem 会记录失败并重新抛出异常，使消息保持待处理状态以便稍后重试。没有 Claude SDK 回退机制——早期文档声称会自动回退到 Claude，但该接线从未在生产环境中真正启用（#2087）。要切换 provider，请在设置中更改 CLAUDE_MEM_PROVIDER。

触发异常的条件： - 限流（HTTP 429） - 服务器错误（HTTP 500、502、503） - 网络问题（连接被拒绝、超时） - 除 429 以外的 4xx 错误 - 缺少 API 密钥

多轮对话支持¶

OpenRouter agent 会跨 API 调用维护完整的对话历史：

Session Created
  ↓
Load Pending Messages (observations from queue)
  ↓
For each message:
  → Add to conversation history
  → Call OpenRouter API with FULL history
  → Parse XML response
  → Store observations in database
  → Sync to Chroma vector DB
  ↓
Session complete

这实现了： - 连贯的多轮交流 - 跨观察结果保留上下文 - 会话中途无缝切换 provider

故障排除¶

"未配置 OpenRouter API 密钥"¶

可以这样做： - 在 ~/.claude-mem/settings.json 中设置 CLAUDE_MEM_OPENROUTER_API_KEY，或 - 设置 OPENROUTER_API_KEY 环境变量

速率限制¶

免费模型在高峰使用时段可能会有限速。如果遇到限速： - 代理会抛出异常并让消息保持待处理状态——稍后会重试 - 考虑切换为其他免费模型 - 为获得高级模型访问权限而充值

模型不可用¶

当 OpenRouter 报告配置的模型已退役（“This model has been deprecated”）、未知（“is not a valid model ID”）或没有剩余端点（“No endpoints found for …”）时，观察器会报告 OpenRouter model unavailable。重试无法解决该问题，因此不会重试；worker 日志和会话开始警告会提示您更改模型： - 从 OpenRouter Models 中选择一个模型，并将其设置为 ~/.claude-mem/settings.json 中的 CLAUDE_MEM_OPENROUTER_MODEL（或在查看器的 Settings 中设置）。下一次观察将使用该模型 - 使用 :free 后缀来指定免费模型变体 - 模型 ID 区分大小写

如果您仍在使用已退役的默认模型 xiaomi/mimo-v2-flash:free，claude-mem 在首次加载设置时已为您切换到 cohere/north-mini-code:free。

高 Token 用量¶

如果会话积累了大量的对话历史，请求体量可能会增长。为控制每个请求的大小： - 选择适合您使用量的模型 - 如果遇到提供商限制，请考虑使用上下文窗口更大的模型

连接错误¶

如果您看到连接错误： - 检查您的互联网连接 - 在 status.openrouter.ai 查看 OpenRouter 服务状态 - 代理会抛出异常并让消息保持待处理状态，以便稍后重试

API 详情¶

OpenRouter 使用与 OpenAI 兼容的 REST API：

端点：https://openrouter.ai/api/v1/chat/completions

请求头：

Authorization: Bearer {apiKey}
HTTP-Referer: https://github.com/thedotmack/claude-mem
X-Title: claude-mem
Content-Type: application/json

请求格式：

{
  "model": "cohere/north-mini-code:free",
  "messages": [
    {"role": "system", "content": "..."},
    {"role": "user", "content": "..."}
  ],
  "temperature": 0.3,
  "max_tokens": 4096
}

服务提供商对比¶

后续步骤¶

• 配置 - 完整设置参考
• Gemini 提供商 - 替代免费提供商
• 入门指南 - 基本使用指南
• 故障排除 - 常见问题

多个密钥¶

CLAUDE_MEM_OPENROUTER_API_KEYS 可接受额外的密钥（以换行符或逗号分隔），与 CLAUDE_MEM_OPENROUTER_API_KEY 一起使用。当某个密钥触发速率限制、用尽配额或被判定为无效时，OpenRouter 请求会轮换到下一个密钥，而不会在窗口的剩余时间内持续失败。参见 多密钥轮换。