ModelFold Docs

简体中文

English

简体中文

English

Appearance

安装 modelfold-chat-agents ​

ModelFold(ai.modelfold.online)的 chat 模型按各家厂商自己的 wire 协议对外提供。agent 的协议和模型的协议一致时,不需要适配层;不一致时,中间要放一个本地翻译代理,见下方「协议不一致时」一节。

一个 agent 一节,每节自成一体:怎么列出该 agent 能跑的模型、它要什么配置、它会怎么失败。目前覆盖了 Codex CLI、Claude Code 和 Grok Build;其他 agent 后续作为并列的章节加进来。协议不一致那一节是共用的,新 agent 不必再写一张配对表。

WARNING

⚠️ 使用 Agent 功能请选择最新版模型

Agent 功能请使用各系列的最新版模型。部分较早的模型目前仅支持对话调用，接入 Agent 可能会出现请求报错或结果异常，这类模型在 Market 的模型页上标有「仅支持对话调用」。具体可用的模型以各 Agent 的模型列表为准。

安装 ​

bash
npx skills add https://ai.modelfold.online/

装好之后,可以直接对 Agent 说,例如“把 Codex 配置成使用 ModelFold”,skill 会按对应 Agent 页面的步骤完成配置。也可以照下面各页手动配置。

先决条件 ​

一个 <https://ai.modelfold.online/account&gt; 上创建的 ModelFold API key,导出为 MODELFOLD_API_KEY,以及装好你要配置的那个 agent。

列模型的片段需要 PATH 上有 curl 和 jq。多数系统不预装 jq:brew install jq、apt install jq 或 winget install jqlang.jq。

PowerShell 的 curl 是 Invoke-WebRequest 的别名,不接受这些参数。要像下面的 Windows 片段那样写 curl.exe。cmd.exe 下片段必须重写,不能直接粘贴。

三个 Agent 一览 ​

以下内容归纳自各 Agent 页面,细节以对应页面为准。

Claude Code ​

  • 协议：Anthropic Messages
  • 列模型：GET https://ai.modelfold.online/anthropic/v1/models
  • 配置位置：环境变量，或 ~/.claude/settings.json 的 env
  • base URL：ANTHROPIC_BASE_URL=https://ai.modelfold.online/anthropic
  • 凭据：原始 key 放进 ANTHROPIC_AUTH_TOKEN

Codex CLI ​

  • 协议：OpenAI Responses
  • 列模型：GET https://ai.modelfold.online/openai/v1/models
  • 配置位置：~/.codex/config.toml 的 [model_providers.ModelFold]
  • base URL：https://ai.modelfold.online/openai/v1
  • 凭据：env_key = "MODELFOLD_API_KEY"

Grok Build ​

  • 协议：Responses（api_backend = "responses"）
  • 列模型：GET https://ai.modelfold.online/xai/v1/models
  • 配置位置：~/.grok/config.toml 的 [model.ModelFold]
  • base URL：https://ai.modelfold.online/xai/v1
  • 凭据：env_key = "MODELFOLD_API_KEY"

三个 Agent 共同的规则:

  1. 模型名从 listing 里取,不要凭记忆写。 每次都重新跑 listing,模型集合会变。
  2. 用 Authorization: Bearer 认证。 名字就叫 apikey 的请求头会被 401 拒掉。
  3. base URL 不要写完整请求 URL。 Agent 会自己往后拼 /v1/messages 或 /responses。
  4. 配置写进用户级文件,不要写进项目级文件。 项目级文件要么被忽略,要么会被提交进仓库。

协议不一致时 ​

本 skill 里每个 agent 说一种 wire 协议,ModelFold 的每份 listing 也按一种协议提供。两者一致时,按该 agent 那一节配置,流量打到 ai.modelfold.online。不一致时,需要一个本地翻译代理。

什么时候需要代理 ​

  1. 读该 agent 那一节:它说什么协议、会往后面拼哪一段。
  2. 读模型的 listing:ModelFold 按什么协议提供。
  3. 协议相同:不需要代理。协议不同:告诉用户需要本地翻译代理,并且 动手写之前先问。用户可能已经有代理,也可能这次并不想写。未经询问不要生成代理代码。
  4. 用户已有代理,或明确要求写一个之后,agent 的 base URL 指到代理,不指到 ai.modelfold.online。
  5. 列模型走 模型那一侧 的 listing,不走 agent 原生 listing。agent 的模型配置填那份列表里的 id——它内置的默认名和别名只对原生协议成立。

代理要暴露什么 ​

模型 listingModelFold 请求协议
GET /openai/v1/modelsPOST /openai/v1/responsesResponses
GET /anthropic/v1/modelsPOST /anthropic/v1/messagesMessages
GET /xai/v1/modelsPOST /xai/v1/responsesResponses

代理听的是 agent 会拼出来的那条路径,转到 该 listing 对应的 ModelFold 请求。两个方向都要翻译,包括 agent 实际会发的流式和 tool 调用。打到 ModelFold 的鉴权是 Authorization: Bearer $MODELFOLD_API_KEY。

以后新 agent 的 listing 不在这张表里时,加一行即可。这一节的规则不用改。

写代理时 ​

只有用户明确要求时才写。映射要诚实,不要发明平台行为。

  1. 两种协议的形状从真实 agent 请求和官方协议里学,不要凭记忆填字段。 抓 agent 实际发出的请求(claude --debug、Codex 日志、GROK_LOG_FILE)和 ModelFold 在模型路径上要的形状。凭训练数据拼出来的字段表通常是残的。
  2. model id 原样转发。 不要写死默认模型名,也不要把 sonnet / opus / claude-* 改写成 GPT slug,反过来也不要。
  3. 若代理要接 GET /models,返回的是 agent 期望的列表形状,数据来自模型那一侧的 ModelFold listing。 把另一边的文档原样转过去形状是错的。listing 失败就是错误,不要编一条假模型。
  4. 工具调用必须能走完一轮。 id / call_id / tool_use_id 在请求和下一轮的 tool result 里保持一致。不要丢掉 tools。ModelFold 若拒绝 tools,把那个错误传回去。
  5. 流式必须按 agent 结束一轮的方式收尾。 发出该 agent 会消费的事件序列,包括终态事件。ModelFold 中途报错或断流时,agent 必须看到失败,而不是 HTTP 200 加一轮空的 completed。
  6. 不要为了绕过协议限制而塞进新的 user/assistant 内容。 有的 Messages 模型拒绝以 assistant 收尾的对话。编一条后续 user 能让请求合法,但会改掉这一轮的语义——Codex 会因此不停续写。要么无损改形状,要么把服务端错误原样返回。

把 agent 指到代理 ​

监听地址是代理自己绑的。agent 的 base URL 仍按它那一节的规则写——Claude Code 会给 ANTHROPIC_BASE_URL 拼 /v1/messages,Codex 会给 base_url 拼 /responses,Grok Build 在 api_backend = "responses" 时也会给 base_url 拼 /responses——所以值里不要带上这段后缀。

把规则用到 Claude Code 跑 Responses 模型:

bash
export ANTHROPIC_BASE_URL=http://127.0.0.1:<port>
export ANTHROPIC_AUTH_TOKEN=$MODELFOLD_API_KEY
export ANTHROPIC_MODEL=…

ANTHROPIC_MODEL 是 GET /openai/v1/models 里的 id,不是 Claude Code 的 sonnet / opus 别名。

把规则用到 Codex CLI 跑 Messages 模型:

toml
model = "…"
model_provider = "ModelFold"

[model_providers.ModelFold]
name = "ModelFold"
base_url = "http://127.0.0.1:<port>/v1"
env_key = "MODELFOLD_API_KEY"
wire_api = "responses"

model 是 GET /anthropic/v1/models 里的 id。base_url 仍然不要带 /responses。

不要一边让 agent 的 base URL 还指着 ai.modelfold.online,一边发另一份 listing 里的 id;也不要把 agent 直接指到模型那一侧的 ModelFold 前缀而不经翻译。

本 skill 不提供什么 ​

本 skill 不包含、不生成、也不点名任何翻译代理。它只声明监听路径、ModelFold 路径、该读哪份 listing,以及 agent 里哪个配置项填代理地址。只有用户明确要求时才写代理代码。

ModelFold — 一个 API，接入所有主流 AI 模型。

© 2026 ModelFold