LiteLLM 网关¶

claude-mem 可以将其后台记忆代理通过 LiteLLM 代理进行路由。这样，团队可以在使用 LiteLLM 进行模型路由、集中式凭据、用量跟踪、预算、审计日志和提供商故障转移的同时，继续使用 claude-mem 的 Claude Agent SDK 工作流。

重要细节：claude-mem 不会直接使用 OpenAI 客户端调用 LiteLLM。claude-mem 仍然使用 Claude Agent SDK，SDK 会将 Anthropic 格式的请求发送到 LiteLLM。然后，LiteLLM 会将这些请求转换为你所配置的上游模型提供商。

Claude Code session
  -> claude-mem hooks
  -> claude-mem worker
  -> Claude Agent SDK subprocess
  -> ANTHROPIC_BASE_URL=http://localhost:4000
  -> LiteLLM proxy
  -> OpenAI / Azure / Vertex / Bedrock / OpenRouter / local model

这使记忆代理始终保持单一实现路径。无论上游模型是 Anthropic 还是通过 LiteLLM 路由，Claude 提供商、知识代理、会话恢复行为、XML 观察提示和队列重试逻辑都继续使用相同的 SDK 代码路径。

何时使用¶

当你希望实现以下目标时，可使用 LiteLLM 网关模式：

• 用于 claude-mem 流量的单一组织级 LLM 网关
• 无需更改 claude-mem 源代码即可实现提供商路由
• 集中管理 API 密钥，而不是将提供商密钥存储在每个开发者的 claude-mem 设置中
• LiteLLM 预算、速率限制、日志记录、回退路由或虚拟密钥
• 使用非 Anthropic 上游模型，同时保留 claude-mem 所用的 Claude Agent SDK 执行路径

如果你希望直接使用 claude-mem 的 REST 提供商，且不需要 Claude Agent SDK 路径，请改用原生 OpenRouter 提供商 或 Gemini 提供商。

架构¶

单一代理路径¶

LiteLLM 集成刻意保持小巧。claude-mem 中没有自定义 LiteLLM 提供商、没有 Python 处理器，也没有内嵌的 OpenAI 兼容服务器。

运行时：

1. 安装程序或用户将网关设置写入 ~/.claude-mem/.env。
2. ~/.claude-mem/settings.json 将 CLAUDE_MEM_PROVIDER 保持为 claude。
3. 工作进程在隔离环境中启动 Claude Agent SDK。
4. SDK 读取 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN。
5. LiteLLM 接收 SDK 的 Anthropic 格式请求。
6. LiteLLM 将请求映射到 LiteLLM 中配置的上游提供商和模型。
7. SDK 响应由常规的 claude-mem 观察流水线解析。

涉及的代码路径如下：

为什么 CLAUDE_MEM_PROVIDER 保持为 claude¶

LiteLLM 是 Claude Agent SDK 路径的网关，而不是第四个 claude-mem 提供商。

{
  "CLAUDE_MEM_PROVIDER": "claude",
  "CLAUDE_MEM_CLAUDE_AUTH_METHOD": "gateway",
  "CLAUDE_MEM_MODEL": "claude-haiku-4-5-20251001"
}

将提供商保持为 claude 很重要，因为工作进程应继续使用 ClaudeProvider，而不是原生的 Gemini 或 OpenRouter REST 提供商。网关 URL 改变了 SDK 发送模型流量的目标位置；它不会改变 claude-mem 管理记忆会话的方式。

配置 LiteLLM¶

LiteLLM 必须为 Claude Code / Claude Agent SDK 流量公开一个兼容 Anthropic 的端点。Anthropic 的网关指南建议将统一的 LiteLLM 端点作为常规配置：

export ANTHROPIC_BASE_URL=http://localhost:4000

对于 claude-mem，该值应放在 ~/.claude-mem/.env 中，而不是你的 shell 中，以便后台工作进程在每次重启后都能一致地使用它。

最小 LiteLLM 示例¶

创建一个 LiteLLM 配置，定义 claude-mem 将请求的模型名称：

# litellm-config.yaml
model_list:
  - model_name: claude-haiku-4-5-20251001
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY

litellm_settings:
  master_key: sk-litellm-local

启动 LiteLLM：

OPENAI_API_KEY=sk-your-openai-key \
litellm --config litellm-config.yaml --host 127.0.0.1 --port 4000

在此示例中，claude-mem 向 SDK 请求 claude-haiku-4-5-20251001，LiteLLM 接受该模型别名，并将请求转发到 openai/gpt-4o-mini。

配置 claude-mem¶

选项 1：安装程序¶

运行安装程序：

npx claude-mem install

选择：

1. Claude Agent SDK
2. API key or gateway
3. LiteLLM or custom gateway
4. 你的 LiteLLM URL，例如 http://127.0.0.1:4000
5. 如果代理需要，提供你的 LiteLLM 密钥/令牌
6. LiteLLM 应该接收的模型别名

安装程序将提供商设置存储在 ~/.claude-mem/settings.json 中，将网关凭据存储在 ~/.claude-mem/.env 中。

选项 2：手动编辑文件¶

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

{
  "CLAUDE_MEM_PROVIDER": "claude",
  "CLAUDE_MEM_CLAUDE_AUTH_METHOD": "gateway",
  "CLAUDE_MEM_MODEL": "claude-haiku-4-5-20251001"
}

编辑 ~/.claude-mem/.env：

# ~/.claude-mem/.env
ANTHROPIC_BASE_URL=http://127.0.0.1:4000
ANTHROPIC_AUTH_TOKEN=sk-litellm-local

如果你的 LiteLLM 代理不需要身份验证，请省略 ANTHROPIC_AUTH_TOKEN。

手动编辑后重启工作进程：

npm run worker:restart

环境隔离¶

claude-mem 刻意不信任你的 shell 或项目 .env 文件中恰好导出的任何 Anthropic 凭据。

工作进程会屏蔽继承的 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 以及过期的 CLAUDE_CODE_OAUTH_TOKEN 值。然后仅重新注入存储在 ~/.claude-mem/.env 中的凭据。

这可以避免两种常见故障模式：

• 项目级 ANTHROPIC_API_KEY 会静默绕过 LiteLLM，并将费用计入公共 Anthropic API。
• 过期的 Claude Code OAuth 令牌会覆盖已配置的网关令牌，导致令人困惑的认证失败。

如果 ~/.claude-mem/.env 中存在 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY，工作进程会将其视为显式的网关/API 配置，并跳过 Claude OAuth 查找。这可以防止已配置的网关回退到 api.anthropic.com。

模型名称¶

CLAUDE_MEM_MODEL 会直接传递给 Claude Agent SDK。在网关模式下，claude-mem 允许任何非空模型字符串，因为有效模型列表由 LiteLLM 维护。

推荐配置模式：

model_list:
  - model_name: claude-haiku-4-5-20251001
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY

然后保留：

{
  "CLAUDE_MEM_MODEL": "claude-haiku-4-5-20251001"
}

或者，使用具有描述性的自定义别名：

model_list:
  - model_name: memory-compressor
    litellm_params:
      model: azure/gpt-4o-mini-memory
      api_base: os.environ/AZURE_API_BASE
      api_key: os.environ/AZURE_API_KEY
      api_version: "2024-10-21"

{
  "CLAUDE_MEM_MODEL": "memory-compressor"
}

请求流程¶

当 Claude Code 会话产生转录事件时，claude-mem 的工作进程会将它们排入队列以进行观察提取。在网关模式下，提取流程如下：

1. 工作进程为记忆会话加载待处理的消息。
2. ClaudeProvider 构建观察 prompt 和所选模型。
3. buildIsolatedEnvWithFreshOAuth() 加载 ~/.claude-mem/.env。
4. SDK 子进程启动，ANTHROPIC_BASE_URL 指向 LiteLLM。
5. LiteLLM 接收 Anthropic 格式的请求。
6. LiteLLM 将请求路由到配置的上游模型。
7. SDK 将助手响应流式传输回工作进程。
8. claude-mem 解析观察结果，将其存储在 SQLite 中，并同步可搜索的嵌入向量。

knowledge-agent API 使用相同的网关环境，因此语料库预置和语料库问答也会通过 LiteLLM 路由。

LiteLLM 能替代与不能替代的内容¶

LiteLLM 可以替代：

• 上游模型选择
• 提供商凭据
• 网关级预算和速率限制
• 网关级日志记录和审计
• LiteLLM 内部的可选路由/回退策略

LiteLLM 不能替代：

• claude-mem 的工作进程
• Claude Agent SDK 子进程
• claude-mem 的观察 XML 格式
• SQLite 存储
• Chroma/向量同步
• Hook 安装
• claude-mem 内部的会话恢复处理

验证¶

查看 claude-mem 的工作进程日志：

npm run worker:logs

你应该会看到报告网关认证的 SDK 启动日志，之后是正常的观察处理日志。

查看 LiteLLM 日志中是否有发送到配置的模型别名的请求。如果 LiteLLM 从未收到流量，请确认：

• CLAUDE_MEM_PROVIDER 是 claude
• CLAUDE_MEM_CLAUDE_AUTH_METHOD 是 gateway
• ANTHROPIC_BASE_URL 位于 ~/.claude-mem/.env
• 手动编辑后已重启工作进程
• LiteLLM URL 不包含用于统一 Anthropic 端点的额外 /v1 后缀

故障排除¶

LiteLLM 返回 “model not found”¶

claude-mem 发送的模型名称与 LiteLLM 的 model_name 不匹配。请让 CLAUDE_MEM_MODEL 与 LiteLLM 别名完全一致。

claude-mem 仍直接使用 Anthropic¶

检查 ~/.claude-mem/.env。网关设置必须存储在那里。Shell 导出变量并不是工作进程的可靠配置来源。

同时确保存在 ANTHROPIC_BASE_URL。仅有令牌可以认证网关，但真正将流量从默认 Anthropic 端点重定向开的是基础 URL。

认证失败¶

如果 LiteLLM 使用主密钥或虚拟密钥，请将其作为 ANTHROPIC_AUTH_TOKEN 存储在 ~/.claude-mem/.env 中。Claude Agent SDK 会将该值作为网关授权发送。

如果你之前配置了直接的 Anthropic API 密钥，在网关模式下，请从 ~/.claude-mem/.env 中移除 ANTHROPIC_API_KEY，除非你的网关明确需要该变量。

修改文件后请求失败¶

重启工作进程：

npm run worker:restart

SDK 环境是在 SDK 子进程被生成时构建的。重启可确保下一个内存代理进程能看到新的网关值。

工具使用行为与完整 Claude Code 不同¶

claude-mem 的记忆工作进程会禁用文件和 shell 工具以进行观察提取。LiteLLM 网关仅处理用于压缩和总结记忆的模型调用；它不能替代你的交互式 Claude Code 工具循环。

相关文档¶

• 自定义 Anthropic 兼容后端
• 配置
• Worker Service 架构
• Anthropic LLM 网关配置
• LiteLLM 文档