OpenAI 兼容接入

Matrix 提供 OpenAI 兼容接口，几乎任何支持自定义 base_url 的客户端都可以无缝接入。

通用配置项

Base URL : <Matrix 网关地址>/v1
API Key  : 你在控制台生成的 Matrix Key（以 `mat-` 开头的字符串）
Model    : 任意 Matrix 已接入的模型名

Matrix 当前网关地址会显示在 API Key 控制台 的 Key 详情页面。

代码示例

Python (openai SDK ≥ 1.0)

from openai import OpenAI

client = OpenAI(
    base_url="<Matrix 网关地址>/v1",
    api_key="<你的 Matrix Key>",
)

resp = client.chat.completions.create(
    model="GLM-4.7",
    messages=[{"role": "user", "content": "用一句话介绍 Matrix"}],
    temperature=0.7,
)
print(resp.choices[0].message.content)

流式响应

stream = client.chat.completions.create(
    model="GLM-4.7",
    messages=[{"role": "user", "content": "写一首关于代码的诗"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Node.js / TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "<Matrix 网关地址>/v1",
  apiKey: process.env.MATRIX_KEY!,
});

const res = await client.chat.completions.create({
  model: "Qwen3.5-397B-A17B",
  messages: [{ role: "user", content: "Hello" }],
});

cURL

curl <Matrix 网关地址>/v1/chat/completions \
  -H "Authorization: Bearer <你的 Matrix Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "GLM-4.7",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

客户端配置速查

客户端	关键配置位置	注意事项
Cursor	Settings → Models → OpenAI API Key + Custom Base URL	Override 选项要勾选
Cherry Studio	模型 → 添加自定义 Provider → 类型选 OpenAI 兼容	Provider 类型必须是 OpenAI 兼容
Open WebUI	Admin → Connections → OpenAI API	URL 末尾要带 /v1
LobeChat	Settings → 模型服务商 → OpenAI → 自定义 Base URL	同时填模型清单
Continue.dev	config.json → models 加自定义条目	provider 设 openai
Aider	--openai-api-base + --openai-api-key	启动时传入

排错

• 401 / 403：Key 错或被禁用，去 API Key 控制台 确认状态
• 404 model not found：模型名拼写错或没接入，到 模型列表 查
• 没有响应 / hang：检查客户端是否走代理；尝试关掉代理或加 Matrix 网关到白名单
• 客户端不支持 base_url 自定义：用 nginx / Caddy 做反代，把官方 OpenAI 域名映射到 Matrix 网关

用量观测

所有走 Matrix Key 的调用都会被记录，详细数据：用量统计

• 按 Key 维度：哪把 Key 跑多少
• 按模型维度：哪个模型最贵
• 按时间窗：高峰低谷分布