convez.ai
MCP ServerIntegração & APIsAvançado
Mars535821089-ops

MiniMax-Claude-Proxy

Mars535821089-ops/MiniMax-claude-proxy

Proxy que harmoniza MiniMax-M3 com protocolo Anthropic do Claude Code

Ver no GitHub
BomPluginScore · de 0 a 100

Proxy local que implementa 6 recursos específicos do Anthropic para o modelo MiniMax-M3 funcionar nativamente no Claude Code. Resolve limitações de cache, pensamento estendido, schemas complexos, multimodal e estabilidade SSE através de replicação e contorno de protocolos.

Instalação

$npx convez-ai Mars535821089-ops/MiniMax-claude-proxy

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 3 meses
Versão
v0.1.1
Issues abertas
0
Contribuidores
1

Casos de uso

  • Integrar MiniMax-M3 no ecossistema Claude Code com suporte total
  • Contornar limitações de protocolo em modelos de terceiros
  • Implementar caching persistente e pensamento estendido localmente

Veredito

Solução técnica madura e bem documentada para integração transparente de modelos alternativos no Claude Code. Implementação complexa e especializada, indicada para equipes que precisam estender o ecossistema Anthropic com modelos de terceiros mantendo compatibilidade total.

README

A tradução para o português deste README ainda está na fila.

MiniMax-Claude-Proxy

🔌 在 Claude Code 框架下完整释放 MiniMax-M3 能力的本地代理

补齐 6 大 Anthropic 协议短板,让第三方模型在 Claude Code 中跑得跟原生一样稳。

🇺🇸 English | 🇨🇳 简体中文

📖 完整文档已上线:https://mars535821089-ops.github.io/MiniMax-claude-proxy/latest/ (mkdocs + Material 主题 + 中文搜索)


📑 目录


🤔 这是啥?

Claude Code 客户端默认是为 Anthropic Claude 设计的,依赖一批 Anthropic 独家的协议特性。 MiniMax-M3 通过"Anthropic 兼容"接口接进来时,这批特性多数不工作,导致: 工具调用失败、PDF 看不到、长任务被切断、subagent 出错报告。

本项目是一个本地代理,嵌在 Claude Code 和 MiniMax-M3 之间,把这些 Anthropic 特性 全部在本地重新实现或绕过掉,对客户端保持完全透明。


🎯 它解决什么

#Anthropic 独有能力没代理时的影响本代理怎么做
①Prompt Caching (cache_control)长会话烧 token、Skill 反复重传SQLite 持久化前缀缓存 + cache_control 剥离 + 响应级 KV 缓存 + usage 占位回填
②Extended ThinkingPlan 模式 / 深度推理失效system 注入 <thinking> 引导 + 流式标签拆分回填为 thinking block
③复杂 tool_use schemaTodoWrite/Edit 工具参数出错递归展开 $ref、拍平 oneOf/anyOf、响应后还原嵌套
④多模态图/PDF 看不到图片自动缩放、PDF→文本+关键页转图、URL→base64 拉取
⑤长输出 SSE 稳定性长任务被代理切断15s 心跳 ping + tool_use 整块缓冲 + cache usage 占位注入 + event_id 续传
⑥Server-side Tools (web_search/code_execution/bash)工具不可用本地实现 DuckDuckGo 搜索 + subprocess 沙箱 + 拦截 round-2 回灌答案

🏗️ 架构

flowchart LR
    CC["<b>Claude Code</b><br/>Anthropic SDK"]
    Proxy["<b>MiniMax-Claude-Proxy</b>"]
    Upstream["<b>MiniMax-M3</b><br/>/anthropic API"]
    DB[("SQLite<br/>cache.db")]

    CC -- "POST /v1/messages<br/>(SSE stream)" --> Proxy

    subgraph PRE["前置 pipeline"]
        direction TB
        P1["model_mapping<br/>(claude-* → MiniMax-M3)"]
        P2["cache_control_strip"]
        P3["thinking.preprocess<br/>(注入 system)"]
        P4["schema.preprocess<br/>(拍平 $ref/oneOf)"]
        P5["ssr_tools.preprocess<br/>(翻译为普通工具)"]
        P6["multimodal.preprocess<br/>(图片/PDF)"]
        P7["cache.touch_prefix<br/>(注入 usage 占位)"]
        P1 --> P2 --> P3 --> P4 --> P5 --> P6 --> P7
    end

    subgraph POST["后置 pipeline"]
        direction TB
        Q1["thinking.stream_transformer<br/>(拆标签)"]
        Q2["sse.wrap<br/>(心跳+tool_use 缓冲+占位)"]
        Q3["schema.postprocess<br/>(嵌套还原)"]
        Q4["ssr_tools.execute<br/>(本地工具+回灌)"]
        Q1 --> Q2 --> Q3 --> Q4
    end

    Proxy -- "请求" --> PRE
    PRE -- "清洗后 payload" --> Upstream
    Upstream -- "SSE/JSON 响应" --> POST
    POST -- "客户端透明<br/>(cache_control/thinking/schema 都还原)" --> CC
    PRE -.读/写.-> DB
    POST -.读/写.-> DB

    classDef upstream fill:#fef3c7,stroke:#d97706,color:#000
    classDef proxy fill:#dbeafe,stroke:#1d4ed8,color:#000
    classDef store fill:#f3e8ff,stroke:#7c3aed,color:#000
    class Upstream upstream
    class Proxy proxy
    class DB store

详见 docs/architecture.md。

6 大块能力如何串联

flowchart LR
    subgraph Front["📥 请求进入"]
        A1["① 缓存命中?<br/>查 SQLite prefix"]
        A2["② thinking 标签<br/>注入 system"]
        A3["③ schema 拍平<br/>oneOf/anyOf → flat"]
        A4["④ 多模态预处理<br/>图片缩放/PDF 拆页"]
        A5["⑤ 模型重映射<br/>claude-* → MiniMax-M3"]
        A6["⑥ SSR 工具翻译<br/>web_search 改普通 tool"]
    end

    subgraph Back["📤 响应回传"]
        B1["① 用量占位回填<br/>cache_*/read tokens"]
        B2["② thinking 块拆分<br/>标签 → thinking block"]
        B3["③ 嵌套还原<br/>flat → 原始 oneOf 结构"]
        B4["④ 媒体直出<br/>(已是 base64)"]
        B5["⑤ 模型 ID 一致"]
        B6["⑥ SSR 工具执行<br/>本地实现 + round-2 回灌"]
    end

    Front --> Up["🚀 上游<br/>MiniMax-M3"] --> Back

性能对比(缓存命中 217× 提速)

场景首次请求二次请求(命中)提速
简单中文问答~2.17s0.01s🚀 217×
Prompt Caching 同一会话2.10s0.01s210×
复杂 tool_use schema1.85s0.01s185×

数据来自 MILESTONES.md 真上游回归测试,2026-06-12。

测试状态(21/21 PASS)

tests/test_basic.py::test_strip_cache_control_recursive PASSED           [  4%]
tests/test_basic.py::test_thinking_inject_system PASSED                  [  9%]
tests/test_basic.py::test_thinking_split_text_block PASSED               [ 14%]
tests/test_basic.py::test_schema_flatten_oneof PASSED                    [ 19%]
tests/test_basic.py::test_schema_reconcile_string_to_object PASSED       [ 23%]
tests/test_basic.py::test_ssr_tools_translate_web_search PASSED          [ 28%]
tests/test_basic.py::test_encode_sse_basic PASSED                        [ 33%]
tests/test_basic.py::test_sse_stabilizer_buffers_tool_use PASSED         [ 38%]
tests/test_e2e.py::test_e2e_health PASSED                                [ 42%]
tests/test_e2e.py::test_e2e_count_tokens PASSED                          [ 47%]
tests/test_e2e.py::test_e2e_basic_non_stream PASSED                      [ 52%]
tests/test_e2e.py::test_e2e_cache_control_stripped PASSED                [ 57%]
tests/test_e2e.py::test_e2e_thinking_injected PASSED                     [ 61%]
tests/test_e2e.py::test_e2e_schema_oneof_flattened PASSED                [ 66%]
tests/test_e2e.py::test_e2e_ssr_tool_translated PASSED                   [ 71%]
tests/test_e2e.py::test_e2e_cache_hit_second_call PASSED                 [ 76%]
tests/test_e2e.py::test_e2e_cache_hit_with_claude_model_mapping PASSED   [ 80%]
tests/test_e2e.py::test_e2e_streaming_basic PASSED                       [ 85%]
tests/test_e2e.py::test_e2e_streaming_tool_use_buffered PASSED           [ 90%]
tests/test_e2e.py::test_e2e_ssr_tool_round2_executes PASSED              [ 95%]
tests/test_e2e.py::test_e2e_usage_cache_placeholder PASSED               [100%]

======================= 21 passed, 2 warnings in 13.92s ========================

🚀 快速开始

0. 前置要求

0. 前置要求

  • Python 3.10+(推荐 3.12)
  • MiniMax-M3 API Key(申请地址)
  • 可选:git 用于克隆,curl 用于测试

1. 克隆 + 安装

git clone https://github.com/Mars535821089-ops/MiniMax-claude-proxy.git
cd MiniMax-claude-proxy
bash scripts/install.sh

install.sh 会做:

  1. 创建 .venv 虚拟环境
  2. 安装 requirements.txt 全部依赖
  3. 拷贝 config.yaml.example → config.yaml
  4. 创建 ~/.MiniMax-claude-proxy/launch.sh 启动器

2. 配置

编辑 config.yaml:

upstream:
  base_url: "https://api.minimaxi.com/anthropic"
  api_key: "sk-cp-填入您的真实key"
  model_id: "MiniMax-M3"

🛡️ proxy 启动时强制校验 API Key:必须是 ASCII,且不能是占位文本。

3. 启动

bash scripts/start.sh
# → INFO MiniMax-claude-proxy v0.1.0 listening on 127.0.0.1:8787

4. 让 Claude Code 走代理

临时(关终端就失效):

export ANTHROPIC_BASE_URL=http://127.0.0.1:8787
export ANTHROPIC_API_KEY=any-non-empty
export ANTHROPIC_MODEL=MiniMax-M3
claude

永久(写入 ~/.zshrc 或 ~/.bashrc):

echo 'export ANTHROPIC_BASE_URL=http://127.0.0.1:8787' >> ~/.zshrc
echo 'export ANTHROPIC_API_KEY=any-non-empty' >> ~/.zshrc
echo 'export ANTHROPIC_MODEL=MiniMax-M3' >> ~/.zshrc
source ~/.zshrc

启动 claude,所有请求会经过代理,6 大块功能自动激活。

5. 验证

# 健康检查
curl http://127.0.0.1:8787/v1/health

# 发个简单消息
curl -X POST http://127.0.0.1:8787/v1/messages \
  -H "x-api-key: any" -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"MiniMax-M3","max_tokens":100,
       "messages":[{"role":"user","content":"你好"}]}'

⚙️ 配置

config.yaml 全部配置项有中文注释。常用调优:

想做的事怎么改
缓存命中更激进cache.strategy: prefix + 调大 default_ttl
关掉 thinking 引导(节省 token)thinking.enabled: false
换搜索后端为 Serperserver_side_tools.web_search.backend: serper + export SERPER_API_KEY=...
代码执行更宽松server_side_tools.code_execution.timeout: 60
PDF 只抽文本不转图multimodal.pdf.strategy: text
SSE 心跳更频繁server.sse_ping_interval: 5
把 claude-opus-4-6 映射到不同 MiniMax 模型编辑 model_mapping

环境变量覆盖(无需改配置文件):

变量作用
MINIMAX_API_KEY覆盖 upstream.api_key
MINIMAX_BASE_URL覆盖 upstream.base_url
MINIMAX_PROXY_HOST覆盖 server.host
MINIMAX_PROXY_PORT覆盖 server.port
MINIMAX_PROXY_CONFIG自定义 yaml 路径
SERPER_API_KEYweb_search 选 serper 后端时需要

📡 端点

路径方法说明
/GET服务信息
/v1/healthGET详细健康检查
/v1/messagesPOSTAnthropic Messages API 兼容主端点(支持流式 + 非流式)
/v1/messages/count_tokensPOSTtoken 估算(避免 Claude Code 404)

🧪 开发与测试

跑全部测试

source .venv/bin/activate
pip install pytest pytest-asyncio
pytest tests/ -v

应输出 21 passed(8 单元 + 13 E2E)。

开发模式(热重载)

bash scripts/dev.sh

单独跑某一类测试

# 单元
pytest tests/test_basic.py -v

# E2E(用 mock 上游,无需真 API Key)
pytest tests/test_e2e.py -v

测真实上游(需要 API Key)

# 1. 填好 config.yaml
# 2. 启动
bash scripts/start.sh
# 3. 发请求
curl -X POST http://127.0.0.1:8787/v1/messages \
  -H "x-api-key: any" -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"MiniMax-M3","max_tokens":100,
       "messages":[{"role":"user","content":"用一句话介绍 Python"}]}'

提交 PR

请看 CONTRIBUTING.md。


🛠 部署

场景推荐
个人 macOS + 临时用nohup bash scripts/start.sh &
个人 macOS + 每天用launchd (见 Wiki)
多机 / 团队Docker (见 Dockerfile)
Linux 服务器systemd

详细的 launchd / Docker / systemd 配置见 docs/deploy.md。


🔍 排错 FAQ

症状排查
启动报 upstream.api_key 含非 ASCII 字符把 config.yaml 的 key 换成真 ASCII key(以 sk-cp- 开头)
Claude Code 报 401检查 ANTHROPIC_API_KEY 是否非空(仅作占位,代理不校验)
代理日志 upstream 401检查 config.yaml 的 upstream.api_key
长任务卡住把 server.sse_ping_interval 调小(默认 15s)
tool_use 参数错乱把 schema.flatten_oneof: false 试试
PDF 加载失败pip install pymupdf 验证;或改 multimodal.pdf.strategy: text
缓存不命中检查 sqlite:sqlite3 ~/.MiniMax-claude-proxy/cache.db 查行数
端口被占lsof -i :8787 找进程;改 server.port

更多见 docs/troubleshooting.md。


📊 性能基线

在 MacBook M1 + 本地 127.0.0.1 测试(真上游回归,非 mock):

xychart-beta
    title "二次请求命中缓存耗时(毫秒)"
    x-axis ["首次", "二次命中", "schema 命中", "tool_use 命中"]
    y-axis "耗时 (ms)" 0 --> 2200
    bar [2170, 10, 10, 10]
场景首次二次(命中缓存)提速
简单中文问答~2.17s0.01s217×
流式输出取决于上游流式常驻 1 个心跳 ping—
100 KB 上传~3.5s取决于上游—
Prompt Caching 同一会话2.10s0.01s210×
复杂 tool_use schema1.85s0.01s185×

提示:本代理不会让模型变快,它只让协议层不拖后腿。


🤝 贡献

欢迎 PR / Issue / Discussion!请看 CONTRIBUTING.md。

特别欢迎:

  • 🐛 Good first issues
  • 📝 翻译改进
  • 🌐 新增 web_search / code_execution 后端

🛡 隐私

本项目不收集任何用户数据。所有流量都走您的本地进程和您配置的上游 API。

  • 日志仅记录在本地 stdout(不发送任何地方)
  • SQLite 缓存文件位于 ~/.MiniMax-claude-proxy/cache.db(您自己控制)
  • API Key 绝不会被代理转发到 MiniMax 之外的任何地方

详见 SECURITY.md。


🌟 Star History

如果这个项目对您有帮助,欢迎给个 ⭐ 鼓励一下!


📄 License

MIT © 2026 The MiniMax-Claude-Proxy Authors


🙏 致谢


Ver o original no GitHub

Bom para

Relacionados