企业官网建设流程全解析

1. 为什么需要“大模型网关集成MCP与CLI”这套组合方案？

我第一次在客户现场看到这个需求时，心里其实是有点犯嘀咕的：不就是调用个大模型API吗？写个curl、配个Python requests、甚至用Postman点几下不就完事了？结果客户递过来一张运维日报——过去两周内，37次模型调用失败，其中29次报错是401 Unauthorized，8次是429 Too Many Requests。更麻烦的是，开发团队提交的5个不同服务模块，各自硬编码了密钥、各自管理超时重试逻辑、各自实现鉴权头拼接，连User-Agent都五花八门。当安全团队要求统一轮换密钥时，我们花了整整三天时间，挨个服务查代码、改配置、重启验证，中间还漏掉了一个边缘服务，导致它持续报错两天才被发现。

这就是典型的“密钥散落式管理”灾难。而标题里提到的“大模型网关集成MCP与CLI”，本质上不是炫技，而是把三个原本割裂的环节——模型访问入口（网关）、协议交互标准（MCP）、开发者本地操作界面（CLI）——用一套可复用、可审计、可灰度的机制串起来。关键词里的“自动分配密钥工具”，恰恰是整套方案的锚点：它不生产密钥，而是把密钥的生命周期管理从“人肉复制粘贴”升级为“策略驱动分发”。

你可能已经注意到热词里反复出现的codex cli、claude cli、figma mcp、蓝湖mcp——这些都不是孤立工具，而是同一类问题在不同场景下的解法：前端设计稿要调模型生成文案，后端服务要调模型做意图识别，运维脚本要调模型分析日志……它们都需要一个统一的、带身份上下文的、能自动适配网关策略的HTTP调用通道。MCP（Model Control Protocol）在这里不是某种神秘协议，它本质是一套轻量级的、面向大模型调用场景设计的元协议规范：定义了如何携带模型标识、如何声明调用意图、如何传递上下文约束、如何解析流式响应结构。而CLI，就是把这个协议落地到开发者终端的最短路径。

所以，这不是一篇讲“怎么装个命令行工具”的教程，而是一份面向中大型技术团队的模型调用基础设施建设指南。它解决的不是“能不能调通”，而是“能不能管住、能不能扩、能不能查、能不能换”。如果你正面临密钥满天飞、调用无监控、故障难定位、新模型接入慢等问题，这篇内容里的每一步配置、每一个参数、每一处避坑点，都是我在三个真实项目里踩出来的。

2. 大模型网关的核心职责与MCP协议的落地逻辑

很多团队一上来就想“集成MCP”，但没想清楚网关到底该承担什么角色。我见过最典型的误区，是把网关当成一个简单的反向代理——只做host转发和端口映射。这种做法在单模型、小流量时没问题，一旦接入多个模型（Qwen、Claude、Minimax、自研模型），问题立刻爆发：密钥怎么分发？限流策略怎么差异化？审计日志怎么归因到具体业务方？模型路由规则怎么动态更新？这时候，网关必须从“管道”升级为“控制平面”。

我们当前采用的网关架构，核心由三部分组成：认证中心（AuthZ）、路由引擎（Router）、协议适配层（Adapter）。这三者共同支撑MCP协议的语义落地，而不是简单地透传HTTP请求。

2.1 认证中心：密钥不是字符串，而是策略载体

MCP协议里没有定义密钥格式，但它隐含了一个关键前提：每个密钥必须绑定明确的权限上下文。比如，dev-team-a的密钥只能调用qwen-7b-chat，且QPS上限为5；而prod-analytics的密钥可调用qwen-72b-chat，但禁止流式响应。网关的认证中心，就是把原始密钥字符串解析成这样的策略对象。

实际实现中，我们采用JWT（JSON Web Token）作为密钥载体。密钥本身是一个base64编码的JWT，其payload包含：

{ "sub": "dev-team-a", "aud": ["qwen-7b-chat"], "exp": 1735689600, "rate_limit": {"qps": 5, "burst": 10}, "features": ["sync", "non-streaming"], "iat": 1735603200 }

提示：不要用对称密钥（HMAC）签发这类JWT。我们强制使用RSA256非对称签名，公钥由网关持有，私钥由密钥分发服务（即后文的CLI工具）安全保管。这样即使某个服务的密钥泄露，也只需吊销对应私钥，无需修改网关配置。

网关收到请求后，首先校验JWT签名和有效期，再检查aud字段是否匹配目标模型标识符。如果请求头里写着X-MCP-Model: claude-3-haiku，但JWT的aud里只有qwen-7b-chat，网关直接返回403 Forbidden，并记录审计日志：“密钥dev-team-a尝试越权访问claude-3-haiku”。

2.2 路由引擎：MCP的model字段是路由指令，不是装饰

MCP协议要求请求头或body中必须声明X-MCP-Model（或类似字段）。很多团队把它当成一个可选的metadata，这是巨大风险。在我们的路由引擎里，X-MCP-Model是第一优先级路由键。它的值不是随便填的字符串，而是注册在网关模型目录里的唯一标识符。

模型目录是一个YAML配置文件，示例如下：

models: - id: qwen-7b-chat backend: http://internal-qwen-api:8000/v1/chat/completions auth_type: api_key api_key_header: "Authorization" api_key_prefix: "Bearer " timeout_ms: 30000 health_check: "/health" - id: claude-3-haiku backend: https://api.anthropic.com/v1/messages auth_type: api_key api_key_header: "x-api-key" timeout_ms: 60000 health_check: "/v1/usage"

当网关收到X-MCP-Model: qwen-7b-chat时，它会：

1. 查找目录中id匹配的模型配置；
2. 校验该模型是否在密钥的aud白名单中；
3. 将原始请求体按模型后端要求转换（如将MCP格式的messages数组转为Anthropic的messages结构）；
4. 注入api_key_header指定的认证头；
5. 设置timeout_ms作为本次转发的超时阈值。

注意：X-MCP-Model的值必须全小写、无空格、无特殊字符。我们曾遇到一个前端团队用X-MCP-Model: Qwen-7B-Chat（含大写和连字符），导致路由失败。解决方案是在网关层做标准化预处理：所有模型ID自动转为小写并替换连字符为下划线，同时在文档中明确约定命名规范。

2.3 协议适配层：把MCP语义翻译成后端模型的真实需求

MCP协议本身是抽象的，但每个模型后端的API契约千差万别。协议适配层就是那个“翻译官”。它不改变业务逻辑，只做结构映射和字段转换。

以流式响应为例：MCP协议规定响应头X-MCP-Stream: true表示启用流式，响应体应为SSE（Server-Sent Events）格式，每条event为data: { "delta": "hello" }。但Qwen API返回的是text/event-stream，每条数据是{"id":"xxx","object":"chat.completion.chunk","choices":[{"delta":{"content":"hello"}}]}；而Claude API返回的是application/json，需按\n\n分割。适配层的工作，就是把后端原始响应，按MCP规范重新封装。

我们采用模板化适配策略，为每个模型后端定义一个Jinja2模板：

{%- for chunk in backend_response %} data: {{ chunk | tojson }} \n\n {%- endfor %}

对于Claude，模板会提取choices[0].delta.content；对于Qwen，则提取choices[0].delta.content。这样，上层应用只需关心MCP标准，无需感知底层差异。

实测下来，这套三层架构让模型切换成本从“改代码+测一周”降到“改YAML+重启网关（<30秒）”。上周我们替换了生产环境的Claude 3 Sonnet为Qwen 72B，整个过程运维同学全程在钉钉群里直播，开发同学只改了一行X-MCP-Model值，零故障切换。

3. CLI工具的设计哲学与自动密钥分发机制

CLI（Command Line Interface）不是网关的附属品，而是开发者与网关之间的“信任代理”。它的核心价值，不在于提供几个快捷命令，而在于把密钥分发这个高危操作，变成一次原子化的、可审计的、带上下文的自助服务。

3.1 为什么不能直接给开发者密钥字符串？

这个问题我们内部争论过三次。反对直接分发密钥的理由很实在：

• 密钥泄露面指数级扩大：一个密钥字符串被复制到10个开发者的本地.env文件里，就等于有10个潜在泄露点；
• 无法实时吊销：某个实习生离职，你得手动通知所有服务负责人去删密钥，漏掉一个就留后门；
• 权限颗粒度失控：给A团队的密钥，B团队偷偷拿来用，网关日志里只能看到“密钥xxx”，无法区分是谁在用。

CLI工具的破局点，是引入“密钥租约（Lease）”概念。开发者执行mcp-cli auth login --team dev-team-a时，CLI并不返回密钥字符串，而是向网关发起一个租约申请。网关验证dev-team-a的组织策略后，返回一个短期有效的JWT（默认24小时），并记录租约ID、申请人、设备指纹、IP地址。这个JWT就是开发者后续所有调用的凭证。

3.2 CLI的安装与初始化：避开最常见的环境陷阱

热词里大量出现unable to locate the codex cli binary、mac claude cli 用qwen key，说明安装环节就是第一道坎。我们的CLI基于Go编写，编译为静态二进制，但仍有几个关键依赖需提前确认：

1. 系统级CA证书：CLI需要HTTPS连接网关，若系统CA证书库过旧（如CentOS 6），会报x509: certificate signed by unknown authority。解决方案不是跳过证书校验（绝对禁止！），而是更新系统证书：

   # Ubuntu/Debian sudo apt update && sudo apt install -y ca-certificates # CentOS/RHEL sudo yum update -y ca-certificates

2. Shell配置文件冲突：很多用户把CLI二进制放在/usr/local/bin，但PATH里/usr/local/bin排在/usr/bin之后。当系统自带curl或jq版本过旧时，CLI内部调用会失败。我们强制CLI在启动时检查依赖版本：

   $ mcp-cli version --verbose CLI Version: 1.2.3 Go Version: go1.21.6 curl Version: curl 7.81.0 (x86_64-pc-linux-gnu) ... jq Version: jq-1.6

   如果curl低于7.68.0或jq低于1.6，CLI会提示“依赖版本过低，请升级”。

3. 配置文件位置：CLI默认读取~/.mcp/config.yaml。但Windows用户常误以为是C:\Users\XXX\.mcp\config.yaml，实际是C:\Users\XXX\AppData\Roaming\mcp\config.yaml（因Go的os.UserConfigDir()行为）。我们在首次运行时主动创建目录并写入默认配置，避免静默失败。

3.3 自动密钥分发的完整流程：从申请到生效

整个流程共5步，全部由CLI自动化完成，开发者只需一条命令：

$ mcp-cli auth login --team dev-team-a --scope qwen-7b-chat --reason "daily testing"

1. 步骤1：设备指纹采集
   CLI生成SHA256哈希，输入包括：主机名、当前用户名、CPU序列号（Linux读/sys/class/dmi/id/product_serial，Mac读ioreg -rd1 -c IOPlatformExpertDevice | grep IOPlatformUUID）、网卡MAC地址。哈希值随登录请求发送，用于后续设备绑定。

2. 步骤2：网关策略引擎校验
   网关收到请求，查询dev-team-a的策略：

   • 是否允许申请qwen-7b-chat？
   • 当前租约总数是否超限（如最多5个活跃租约）？
   • --reason是否符合长度和内容规范（禁止含敏感词）？ 若任一条件不满足，返回清晰错误码（如ERR_POLICY_VIOLATION）。

3. 步骤3：JWT签发与存储
   网关用RSA私钥签发JWT，payload包含：

   { "sub": "dev-team-a", "jti": "lease-abc123", // 唯一租约ID "exp": 1735689600, "scope": ["qwen-7b-chat"], "device_fingerprint": "sha256:xxx", "reason": "daily testing" }

   JWT存入Redis，key为lease:abc123，TTL设为JWT过期时间+30分钟（防时钟漂移）。

4. 步骤4：本地配置写入
   CLI收到JWT后，将其存入~/.mcp/lease.jwt，并生成~/.mcp/config.yaml：

   gateway_url: "https://mcp-gateway.internal.company.com" lease_id: "lease-abc123" default_model: "qwen-7b-chat"

5. 步骤5：即时验证
   CLI立即执行一次健康检查调用：

   curl -H "X-MCP-Model: qwen-7b-chat" \ -H "Authorization: Bearer <JWT>" \ https://mcp-gateway.internal.company.com/v1/health

   成功则输出✅ Login successful. Lease valid until 2024-12-31T08:00:00Z；失败则清理本地文件并提示具体原因。

实操心得：我们曾发现某批MacBook M1设备的ioreg命令输出不稳定，导致设备指纹每天变化。解决方案是在CLI里增加指纹缓存机制：首次生成后存入~/.mcp/device_fingerprint，后续启动优先读取缓存，仅当缓存不存在或--force-new-fingerprint参数存在时才重新采集。

4. MCP与HTTP协议的深度协同：复用、超时与错误码治理

MCP不是替代HTTP，而是构建在HTTP之上的语义层。很多团队失败，是因为把MCP当成“另一个协议”，忽略了HTTP本身的工程实践。我们把MCP调用的稳定性，70%押注在HTTP协议的精细治理上。

4.1 HTTP连接复用：为什么keep-alive必须全局开启

热词里反复出现http连接复用，但多数人只知其名不知其害。默认情况下，HTTP/1.1客户端（包括CLI内置的HTTP client）会启用Connection: keep-alive，但网关和后端模型服务若未正确配置，会导致连接泄漏。

我们的网关Nginx配置关键片段：

upstream qwen_backend { server internal-qwen-api:8000; keepalive 32; # 每个worker进程保持32个空闲连接 } server { location /v1/ { proxy_http_version 1.1; proxy_set_header Connection ''; # 清除上游Connection头，避免干扰 proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_pass http://qwen_backend; proxy_next_upstream error timeout http_502 http_503 http_504; } }

重点在proxy_set_header Connection ''：它清除了客户端发来的Connection: keep-alive头，让Nginx自己管理连接复用。否则，客户端和网关之间、网关和后端之间各维持一套keep-alive，极易出现TIME_WAIT堆积。

CLI端同样强化连接池：

httpClient := &http.Client{ Transport: &http.Transport{ MaxIdleConns: 100, MaxIdleConnsPerHost: 100, IdleConnTimeout: 30 * time.Second, TLSHandshakeTimeout: 10 * time.Second, }, }

实测数据显示，开启连接复用后，QPS提升3.2倍，平均延迟下降68%。更重要的是，502 Bad Gateway错误率从1.7%降至0.03%，因为大部分502源于后端连接超时，而非业务逻辑错误。

4.2 超时分级：网关、CLI、后端必须形成时间链

unexpected status 502 bad gateway和the specified http method is not allowed这类错误，90%源于超时设置错位。我们定义三级超时：

关键规则：L1 < L2 < L3，且L2 - L1 ≥ 5s，L3 - L2 ≥ 10s。这个缓冲区用于网络抖动、网关自身处理开销（JWT校验、日志写入等）。

当CLI设置15s超时，网关收到请求后，会注入X-Request-Timeout: 30000头给后端，并启动30s计时器。如果后端在30s内未返回，网关主动断开连接，返回504 Gateway Timeout；如果CLI在15s内先超时，它会发送RST包中断TCP连接，网关捕获后同样返回504，但日志标记为client_timeout。

避坑经验：曾有个团队把CLI超时设为60s，网关设为30s，后端设为120s。结果用户看到504，但日志显示backend_timeout，排查时误以为后端慢，实际是网关主动切断。我们后来在CLI里加入超时诊断模式：mcp-cli call --debug-timeout，会打印每一跳的耗时，精准定位瓶颈。

4.3 错误码治理：用HTTP状态码讲清故障归属

MCP调用失败，必须让用户一眼看懂“谁的问题、怎么修”。我们严格遵循RFC 7231定义的状态码语义，并扩展了MCP专属子状态码：

CLI在收到错误响应时，会解析X-MCP-Error头，输出人性化提示：

$ mcp-cli call --model qwen-7b-chat --prompt "hello" ❌ Request failed: 403 Forbidden Reason: Scope denied — your lease does not permit access to 'qwen-7b-chat'. Hint: Run 'mcp-cli auth list' to see your current scopes, or contact team admin.

这种设计让一线开发者无需翻文档、无需查日志，30秒内就能定位问题根源。

5. 从CLI调用到生产集成：完整的端到端实操链路

理论讲完，现在带你走一遍真实场景：一个电商推荐服务，需要调用Qwen模型生成商品文案。我们将从零开始，展示如何用CLI工具完成密钥获取、本地测试、代码集成、上线监控的全流程。

5.1 第一步：用CLI获取并验证密钥租约

假设你的团队已注册为ecom-recommender，拥有qwen-7b-chat调用权限。

# 1. 下载并安装CLI（Linux x64） curl -L https://mcp-gateway.internal.company.com/cli/mcp-cli-linux-amd64 -o /usr/local/bin/mcp-cli chmod +x /usr/local/bin/mcp-cli # 2. 登录获取租约 $ mcp-cli auth login --team ecom-recommender --scope qwen-7b-chat --reason "prod recommender service" ✅ Login successful. Lease valid until 2024-12-31T08:00:00Z Lease ID: lease-7f8a2b1c # 3. 查看当前租约详情 $ mcp-cli auth list LEASE ID TEAM SCOPE EXPIRES AT REASON lease-7f8a2b1c ecom-recommender qwen-7b-chat 2024-12-31 08:00:00 daily testing # 4. 本地快速测试（模拟服务调用） $ mcp-cli call --model qwen-7b-chat \ --prompt "为iPhone 15 Pro写一段30字内的电商文案，突出钛金属机身" \ --max-tokens 50 { "id": "chatcmpl-xxx", "object": "chat.completion", "created": 1735603200, "model": "qwen-7b-chat", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "iPhone 15 Pro：航空级钛金属机身，轻盈坚固，重塑旗舰新标杆。" } } ] }

注意：mcp-cli call命令会自动读取~/.mcp/config.yaml中的租约JWT，并注入Authorization头。你不需要、也不应该手动拼接token。

5.2 第二步：在Python服务中集成MCP调用

生产服务通常用Python（Flask/FastAPI）或Java（Spring Boot）。这里以Python为例，展示如何安全集成：

# requirements.txt requests==2.31.0 tenacity==8.2.3 # 重试库 # app.py import os import json import requests from tenacity import retry, stop_after_attempt, wait_exponential class MCPClient: def __init__(self): # 从环境变量读取网关地址和租约JWT self.gateway_url = os.getenv("MCP_GATEWAY_URL", "https://mcp-gateway.internal.company.com") self.lease_jwt = os.getenv("MCP_LEASE_JWT") if not self.lease_jwt: raise RuntimeError("MCP_LEASE_JWT environment variable not set") @retry( stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=1, max=10), reraise=True ) def generate_copy(self, product_name: str, features: str) -> str: url = f"{self.gateway_url}/v1/chat/completions" headers = { "Authorization": f"Bearer {self.lease_jwt}", "X-MCP-Model": "qwen-7b-chat", "Content-Type": "application/json", } payload = { "messages": [ { "role": "user", "content": f"为{product_name}写一段30字内的电商文案，突出{features}" } ], "max_tokens": 50, "temperature": 0.7 } try: response = requests.post( url, headers=headers, json=payload, timeout=(10, 30) # connect=10s, read=30s ) response.raise_for_status() data = response.json() return data["choices"][0]["message"]["content"] except requests.exceptions.Timeout: raise RuntimeError("MCP gateway timeout") except requests.exceptions.HTTPError as e: # 解析MCP错误码 error_code = response.headers.get("X-MCP-Error", "unknown") if error_code == "rate_limit_exceeded": raise RuntimeError("Rate limit exceeded, please check quota") raise RuntimeError(f"MCP API error: {error_code}") # 使用示例 client = MCPClient() copy = client.generate_copy("iPhone 15 Pro", "钛金属机身") print(copy) # iPhone 15 Pro：航空级钛金属机身，轻盈坚固，重塑旗舰新标杆。

部署时，关键配置：

• MCP_GATEWAY_URL：设为网关内网地址（如http://mcp-gateway.svc.cluster.local），避免走公网；
• MCP_LEASE_JWT：通过Kubernetes Secret挂载，绝不硬编码在代码里；
• 重试策略：tenacity库确保网络抖动时自动恢复，避免单点故障。

5.3 第三步：上线后的可观测性与问题排查

集成完成不等于结束。我们为MCP调用建立了三层监控：

1. CLI层监控：每次mcp-cli call自动上报指标到Prometheus：

   • mcp_cli_request_total{team="ecom-recommender",model="qwen-7b-chat",status_code="200"}
   • mcp_cli_request_duration_seconds{team="ecom-recommender"}

2. 网关层监控：Nginx日志经Filebeat采集，Grafana看板包含：

   • 按X-MCP-Model分组的QPS、错误率、P95延迟；
   • 按X-MCP-Error分组的错误类型TOP10；
   • 租约活跃数、过期率。

3. 业务层监控：在Python服务中埋点：

   from opentelemetry import trace tracer = trace.get_tracer(__name__) with tracer.start_as_current_span("mcp.generate_copy") as span: span.set_attribute("mcp.model", "qwen-7b-chat") span.set_attribute("mcp.team", "ecom-recommender") copy = client.generate_copy(...) span.set_attribute("mcp.result_length", len(copy))

当某天发现ecom-recommender的qwen-7b-chat调用错误率突增至5%，我们按此链路排查：

• 查Grafana：错误全是429，X-MCP-Error: rate_limit_exceeded；
• 查网关日志：lease-7f8a2b1c在1小时内触发了1200次调用，远超QPS=5的限额；
• 查业务代码：发现推荐服务在用户浏览商品页时，每秒发起20次文案生成请求，未做合并或缓存；
• 修复：在服务层加Redis缓存，相同商品ID的文案缓存1小时，QPS降至0.8，错误率归零。

这套监控体系，让我们能在故障发生3分钟内定位根因，而不是像过去那样“重启试试看”。

6. 常见问题与实战避坑清单：那些文档里不会写的细节

最后，分享几个血泪教训总结的避坑点。这些不是理论缺陷，而是我们在真实生产环境里，用服务器宕机、客户投诉、凌晨三点救火换来的经验。

6.1 “HTTP 405 Method Not Allowed”：不是方法错了，是网关路由错了

热词里有the specified http method is not allowed for the requested resource.，很多人第一反应是“我用了POST，但接口只支持GET”。但在MCP网关场景下，90%的405源于路由路径不匹配。

我们的网关路由规则是：/v1/chat/completions→X-MCP-Model→ 模型后端。但如果开发者误用：

# ❌ 错误：直接调用后端路径 curl -X POST http://mcp-gateway/internal-qwen-api/v1/chat/completions # ✅ 正确：调用网关统一入口 curl -X POST http://mcp-gateway/v1/chat/completions \ -H "X-MCP-Model: qwen-7b-chat" \ -H "Authorization: Bearer xxx"

网关只监听/v1/*路径，/internal-qwen-api/*是后端服务的内部路径，网关根本不处理，直接返回405。解决方案：在CLI里加入路径合法性检查，mcp-cli call命令强制使用网关URL，禁止用户手动拼接后端地址。

6.2 “502 Bad Gateway”：先查网关健康检查，再查后端

unexpected status 502 bad gateway: unknown error是高频报错。网关返回502，只代表“我连不上后端”，但原因可能是：

• 后端服务进程崩溃（systemctl status qwen-api）；
• 后端服务健康检查端点返回非200（如/health返回500）；
• 网关DNS解析失败（nslookup internal-qwen-api）；
• 网关到后端的网络策略阻断（telnet internal-qwen-api 8000）。

我们固化排查顺序：

1. curl -v http://mcp-gateway/v1/health→ 确认网关自身健康；
2. curl -v http://mcp-gateway/v1/backend-health?qwen-7b-chat→ 网关代理的健康检查；
3. kubectl get pods -n qwen→ 确认后端Pod状态；
4. kubectl logs -n qwen qwen-api-xxx→ 查看后端日志。

把这四步写成一个mcp-cli debug health命令，一键执行，节省80%排查时间。

6.3 CLI配置文件被Git污染：.gitignore必须加这三行

开发团队常把~/.mcp/config.yaml误提交到Git，导致密钥泄露。我们强制要求所有项目仓库的.gitignore包含：

# MCP CLI config ~/.mcp/config.yaml ~/.mcp/lease.jwt ~/.mcp/device_fingerprint

更进一步，在CI流水线里加入扫描步骤：

- name: Scan for MCP secrets run: | if grep -r "MCP_LEASE_JWT\|mcp-gateway" .; then echo "❌ MCP secrets detected in code! Please remove and use environment variables." exit 1 fi

6.4 模型切换时的兼容性陷阱：messages结构差异

MCP协议规定messages是数组，但各模型对role值的要求不同：

• Qwen：支持user、assistant、system；
• Claude：支持user、assistant，不支持system，需把system prompt合并到第一个user message；
• OpenAI：支持user、assistant、system、function。

适配层必须做标准化转换。我们在CLI的mcp-cli call命令里加入--normalize-messages开关，自动处理：

# 自动把system消息合并到user消息 $ mcp-cli call --model claude-3-haiku \ --system "你是电商文案专家" \ --user "为iPhone写文案" \ --normalize-messages

CLI会把--system和--user合并为一个user消息，避免Claude返回400。

这些细节，文档里不会写，但它们决定了方案是“能跑通”还是“能扛住生产流量”。当你在深夜收到告警，真正救命的，往往就是其中某一条。

我在实际使用中发现，最有效的习惯是：每次新模型接入，先用CLI跑通mcp-cli call --model xxx --prompt "test"，再查网关日志确认X-MCP-Error为空，最后才写业务代码。省下的调试时间，够喝三杯咖啡。