API Key 与第三方接入
OpenAI 兼容接入
Matrix 提供 OpenAI 兼容接口，几乎任何支持自定义 base_url 的客户端都可以无缝接入。
通用配置项
Base URL : <Matrix 网关地址>/v1
API Key : 你在控制台生成的 Matrix Key（以 mat- 开头的字符串）
Model : 任意 Matrix 已接入的模型名代码示例
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)客户端配置速查
| 客户端 | 关键配置位置 | 注意事项 |
|---|---|---|
| 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 跑多少
- 按模型维度：哪个模型最贵
- 按时间窗：高峰低谷分布