MATCHALL API / CONNECT YOUR AGENT

选好工具,照着连接。

一个 MatchAll 密钥,连接你常用的 AI 工具。先完成准备,再选择下面对应的教程。

先准备 · 约 2 分钟

拿到地址、密钥和模型

  1. 登录后台 → 账户管理,确认至少一个账户显示可用,且已同步模型。
  2. 进入 API Keys,创建密钥,勾选“模型接口”。每个工具用一个独立密钥,便于看用量和设置限额。
  3. 复制新密钥并保存。后续配置中的 YOUR_MATCHALL_KEY 都要换成它,不能填管理员密码。
OpenAI 地址 · 包含 /v1
https://api.maximoraverse.org/v1
默认模型 · 自动选账户
matchall-auto

这是订阅通道,当前调用已授权的 ChatGPT 模型。matchall-pro / matchall-plus 可指定账户;后台“请求记录”会显示实际账户和模型。Claude Code 是工具名称,使用它接入并不意味着调用 Claude 模型。

命令示例:
01

OpenClaw

添加一个自定义提供商,保留已有提供商。

Chat Completions
  1. 在你要接入的 OpenClaw 中打开配置文件 ~/.openclaw/openclaw.json;Windows 是用户目录下的 .openclaw\openclaw.json。先备份。
  2. 把下面的 matchall 提供商合并进已有的 models.providers。不要用整段示例覆盖原配置。替换密钥占位符。
{
  "models": {
    "providers": {
      "matchall": {
        "baseUrl": "https://api.maximoraverse.org/v1",
        "apiKey": "YOUR_MATCHALL_KEY",
        "api": "openai-completions",
        "models": [{
          "id": "matchall-auto", "name": "MatchAll 自动选择",
          "input": ["text"], "contextWindow": 32000,
          "maxTokens": 8192,
          "compat": {
            "supportsDeveloperRole": true,
            "supportsUsageInStreaming": true,
            "supportsTemperature": false
          }
        }]
      }
    }
  }
}
  1. 在该工具的模型选择中选 matchall/matchall-auto。需要默认使用它时,把已有 agents.defaults.model.primary 设置为这个值。
  2. 在自己的实例重新加载配置,发一句“你好”,再让它读取一个测试文件。到 MatchAll 的“请求记录”确认出现新记录。

示例的 32,000 是保守的客户端上下文预算。模型上限由实际模型决定,不能靠填写更大的数字扩容。图片输入需选择支持图片的真实模型,再把 input 改为 ["text","image"]。

OpenClaw 官方配置说明 ↗
02

Hermes

使用工具自带的配置向导。

Chat Completions
  1. 在你自己的 Hermes 所在终端运行:
hermes model
  1. 选 Custom endpoint(自定义地址)。按提示填下面三项;如询问 API 模式,选 Chat Completions。
提示项填写内容
API base URLhttps://api.maximoraverse.org/v1
API key刚创建的 MatchAll 密钥
Model namematchall-auto
  1. 保存后启动 hermes,发送“你好”。已经在会话中时,可输入 /model custom:matchall-auto 选择刚保存的自定义地址。
  2. 到 MatchAll 后台查看本次记录。如果 Hermes 还在调用旧提供商,重新运行向导确认选择的是 Custom endpoint。

向导会保存所选配置。这里只提供接入说明,服务器上正在运行的 Hermes 未被改动。辅助模型可另有配置;希望辅助调用也走这里时,按 Hermes 的辅助提供商说明设置相同地址与密钥。

Hermes 官方接入说明 ↗
03

DeepSeek Harness

在 Web 界面添加“自定义模型 API”。

可选三种协议
  1. 已有 DeepSeek Harness 时,打开它的 Web 页面。新装用户先按官方安装说明安装,然后运行 dsh web。
  2. 进入 设置 → 模型 → 添加模型提供商,选择 自定义模型 API / Custom model API,不要选预设的 DeepSeek 官方提供商。
  3. 按下表填写,点击“获取可用模型 / Fetch available models”,选择 matchall-auto,再保存。
设置项填写内容
Provider IDmatchall(小写)
Base URLhttps://api.maximoraverse.org/v1
API protocolOpenAI Chat Completions(推荐)
Credential / API keyMatchAll 密钥
Model IDmatchall-auto
  1. 新建会话并选择 matchall / matchall-auto,发送“你好”。发现模型失败时可手动添加上面的 Model ID。

也可建立另一个提供商,选 OpenAI Responses(地址仍带 /v1),或 Anthropic Messages(地址用 https://api.maximoraverse.org)。每个提供商只选一种协议。调用的是 GPT 模型,不会因为客户端名字而变成 DeepSeek 模型;DeepSeek 专属搜索、思考格式等功能不由此接口提供。

DeepSeek Harness 官方中文说明 ↗
04

Claude Code

使用 Messages 协议接入已授权的 GPT 模型。

Anthropic Messages
  1. 先安装 Claude Code。在准备运行它的终端粘贴下面的配置,替换密钥占位符。
$env:ANTHROPIC_BASE_URL = "https://api.maximoraverse.org"
$env:ANTHROPIC_AUTH_TOKEN = "YOUR_MATCHALL_KEY"
$env:ANTHROPIC_MODEL = "matchall-auto"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL = "matchall-auto"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "matchall-auto"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "matchall-auto"
$env:CLAUDE_CODE_SUBAGENT_MODEL = "matchall-auto"
$env:ENABLE_TOOL_SEARCH = "false"
claude --model matchall-auto
  1. 启动后输入 /status,确认 Base URL 是 MatchAll 地址,模型是 matchall-auto。
  2. 先发一句“你好”,再请它读取当前目录中的一个测试文件。需要工具权限时,按 Claude Code 自己的提示确认。
  3. 在 MatchAll 后台查看请求:接口应显示 /v1/messages,实际模型显示 GPT。

这里的地址不加 /v1,Claude Code 会自动补上。配置只对当前终端及由它启动的程序生效。支持文本、图片、普通客户端工具、工具结果回传与流式输出;Anthropic 托管工具、签名思考、精确的 Anthropic Token 计数不适用于 GPT 通道,客户端上下文计数可能是估算。关闭 Tool Search 是为了让工具直接发送完整定义。

Claude Pro 订阅仍可用于后台的“编程任务 → Claude Code”,它与这里的 GPT Messages 接入是两个入口。此配置不会将 Claude Pro 变成通用 Claude 模型 API。

Claude Code 官方网关接入说明 ↗
05

Codex CLI

添加 MatchAll 提供商,再用它开始会话。

OpenAI Responses
  1. 先安装 Codex CLI。打开用户目录下的 .codex/config.toml。Windows 路径为 %USERPROFILE%\.codex\config.toml;macOS / Linux 为 ~/.codex/config.toml。文件不存在时创建。
  2. 把下面片段追加到文件末尾。已经存在同名 [model_providers.matchall] 时修改已有段落,不要重复添加。无需更改原有默认提供商。
[model_providers.matchall]
name = "MatchAll API"
base_url = "https://api.maximoraverse.org/v1"
env_key = "MATCHALL_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false
  1. 在当前终端设置 MatchAll 密钥并启动:
$env:MATCHALL_API_KEY = "YOUR_MATCHALL_KEY"
codex -c model_provider='"matchall"' -m matchall-auto
  1. 发送“你好”,再让它读取一个测试文件。后台应看到 /v1/responses 请求及真实用量。

当前提供 HTTP 流式 Responses;WebSocket 未开放,所以示例关闭该传输。你本机的 Codex 登录用于原有提供商,MatchAll 通过自己的 API Key 认证。长会话若提示远程压缩接口不可用,开启新会话并带上需要的摘要;请按真实模型的上下文预算使用。

Codex 官方配置参考 ↗

怎么知道接入成功?

  1. 客户端能收到回复。
  2. 在后台 → 请求记录看到对应密钥的新请求、实际账户和实际模型。
  3. 让客户端读一个无敏感内容的测试文件,能收到文件内容相关的回复,即验证了“模型调用工具 → 客户端执行 → 结果回传”。

想直接检查密钥时,可在终端运行下面命令,成功会列出可用模型:

$key = "YOUR_MATCHALL_KEY"
Invoke-RestMethod -Uri "https://api.maximoraverse.org/v1/models" -Headers @{Authorization = "Bearer $key"}

一次请求是模型一次生成,不等于你发一次消息。Agent 读文件、执行工具和继续回答通常会产生多次请求。可在“用量与限额”按密钥筛选,设置每日 / 每月预算;USD 显示的是等价花费。

遇到问题,先对照这里

现象处理方法
401 / 密钥无效填 MatchAll API Key;确认未撤销、没有多余空格。管理员密码和官方登录密码不能代替它。
403 / 无权调用密钥需要“模型接口”权限;检查账户授权与上游返回原因。
404 / 地址错误OpenAI 地址带一次 /v1;Claude Code 地址不带 /v1。不要把网页的 /dashboard/ 填成 API 地址。
429 / 限额或排队看请求记录与用量限额。多个 Agent 共用账户额度,减少并发;账户切换不会增加官方额度。
模型不存在先用 matchall-auto,或选 /v1/models 返回的真实模型。Claude / DeepSeek 名称不会自动映射为 GPT。
工具不工作确认客户端开了工具权限,并发送完整工具定义和历史。Claude Code 按上例关闭 Tool Search;托管工具使用其对应提供商。
缓存写入“未上报”表示上游未提供该计数,不代表缓存未生效;后台不会伪造为 0。

订阅通道可能忽略采样与输出长度参数;响应头 X-Matchall-Ignored-Parameters 会列出它们。流式用量在结束时提供,模型上游未上报时保留缺失状态。自动切换只在输出开始前发生。图片生成、音频与 Embeddings 不属于当前订阅接口能力。

创建密钥,开始连接 →基础使用说明