Skip to content

安装 Skill ​

首次会话积分消耗偏高属正常现象

Agent 每次请求都会携带固定的工具定义和系统提示(通常有数万 token)。首次会话这部分内容需要写入缓存,按全量输入计费,所以消耗的积分会比较多;之后的请求命中缓存,这部分按低价缓存计费,消耗会明显下降。这是正常现象,并非多扣费。如有大量使用需求,请联系客服,我们可提供优惠。

AI Agents 接入总览:工具、API 地址与常见问题

ModelFold 提供两个 skill,装上后 Agent 就知道怎么用 ModelFold:

skill装上之后
modelfold-models让 Agent 生成图片、视频、语音,调用对话模型
modelfold-chat-agents让 Agent 自动把 Claude Code、Codex、Grok Build 配到 ModelFold

一条命令装好两个 ​

bash
npx skills add https://modelfold.ai -g -a claude-code -a codex -a grok -y

只想装其中一个,加 --skill modelfold-models 或 --skill modelfold-chat-agents。各参数的含义见下文。

装好后设置 API Key(见下文「第 2 步:设置 API Key」),重启 Agent 即可。


让 Agent 生成图片、视频、语音(modelfold-models) ​

modelfold-models 教会 Agent 使用 ModelFold:查模型列表、按模型类型选接口、提交请求、等待结果并保存文件。


先决条件 ​

  • 一个支持 skill 的编程 Agent,例如 Claude Code、Codex、Cursor 或 Grok Build。
  • Node.js 22.20 或更高(npx skills 的要求)。

第 1 步:安装 skill ​

在终端里运行。这条命令可以整段复制,不会停下来提问:

bash
npx skills add https://modelfold.ai --skill modelfold-models -g -a claude-code -a codex -a grok -y
  • --skill modelfold-models 只安装这一个 skill。去掉它会把站点上的 skill 全部装上(还有一个 modelfold-chat-agents)。
  • -g 装到当前用户目录,所有项目可用。不加 -g 时只装进当前项目。
  • -a 指定 Agent。上面三个是 Claude Code、Codex 和 Grok Build。
  • -y 跳过选择。不带 -y 和 -a 时,终端会停下来等你选;没有交互终端时会直接失败,什么都不安装。
  • 不要在项目里不加这些参数地运行。在 Agent 里执行时,CLI 会把全部 skill 写进当前目录下几十个 Agent 文件夹。

装好的位置:

Agent路径
Claude Code~/.claude/skills/modelfold-models
Codex~/.agents/skills/modelfold-models
Grok Build~/.grok/skills/modelfold-models

Claude Code 和 Grok Build 是指向 Codex 那份的软链。

Cursor ​

skills CLI 把 Cursor 当成通用 Agent。加了 -g 时它不会写入 Cursor 的全局目录 ~/.cursor/skills。在项目目录里运行:

bash
npx skills add https://modelfold.ai --skill modelfold-models -a cursor -y

需要在 Cursor 里手动填模型 ID 时,从 全部模型 ID 复制。

技能在该项目的 .agents/skills/modelfold-models。

想在所有项目里给 Cursor 用,全局安装之后再补软链:

bash
mkdir -p ~/.cursor/skills
ln -sfn ~/.agents/skills/modelfold-models ~/.cursor/skills/modelfold-models

以后要更新,把对应的安装命令再运行一次。


第 2 步:设置 API Key ​

skill 从环境变量 MODELFOLD_API_KEY 读取密钥,不需要把密钥写进项目里。

macOS 与 Linux ​

在启动 Agent 的同一个 shell 里导出,或者写进 shell profile(~/.zshrc、~/.bashrc):

bash
export MODELFOLD_API_KEY=your_key

Windows(PowerShell) ​

powershell
$env:MODELFOLD_API_KEY = "your_key"
setx MODELFOLD_API_KEY "your_key"

setx 只对之后新开的窗口生效。想立刻用上,同时设 $env:。


第 3 步:试一下 ​

在已设置 MODELFOLD_API_KEY 的 shell 里重启 Agent,然后直接用自然语言提需求:

text
Use the modelfold-models skill to list the image models on ModelFold, then generate a 1:1 product photo of a white ceramic mug on a light oak table with one of them. Save the image to ./output.

安全 ​

  • 把 API Key 放在环境变量里,不要贴进聊天、截图或会提交到仓库的文件。
  • 密钥泄露后,立即到 控制台 → API Keys 吊销并新建。

编程代理默认推荐 claude-opus-5-5;媒体任务按任务类型另选媒体模型。


让 Agent 配置 Claude Code / Codex / Grok(modelfold-chat-agents) ​

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

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

WARNING

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

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

安装 ​

bash
npx skills add https://modelfold.ai --skill modelfold-chat-agents -g -a claude-code -a codex -a grok -y

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

先决条件 ​

一个 <https://modelfold.ai/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://modelfold.ai/anthropic/v1/models
  • 配置位置:环境变量,或 ~/.claude/settings.json 的 env
  • base URL:ANTHROPIC_BASE_URL=https://modelfold.ai/anthropic
  • 凭据:原始 key 放进 ANTHROPIC_AUTH_TOKEN

四个模型变量都要配置:ANTHROPIC_MODEL 指定主模型,ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL 分别映射三个模型档位。Haiku 一档必填,否则后台小任务可能拿原始 Claude 模型名请求并报错。示例使用 claude-sonnet-5-5、claude-opus-5-5、claude-haiku-5-5,以携带 ModelFold Key 调用 GET https://modelfold.ai/anthropic/v1/models 接口返回的 id 为准。

bash
export ANTHROPIC_BASE_URL=https://modelfold.ai/anthropic
export ANTHROPIC_AUTH_TOKEN=$MODELFOLD_API_KEY
export ANTHROPIC_MODEL=claude-sonnet-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-5-5

PowerShell 和 settings.json 完整示例。

Codex CLI ​

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

Grok Build ​

  • 协议:Responses(api_backend = "responses")
  • 列模型:GET https://modelfold.ai/xai/v1/models
  • 配置位置:~/.grok/config.toml 的 [model.ModelFold]
  • base URL:https://modelfold.ai/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 那一节配置,流量打到 modelfold.ai。不一致时,需要一个本地翻译代理。

什么时候需要代理 ​

  1. 读该 agent 那一节:它说什么协议、会往后面拼哪一段。
  2. 读模型的 listing:ModelFold 按什么协议提供。
  3. 协议相同:不需要代理。协议不同:告诉用户需要本地翻译代理,并且 动手写之前先问。用户可能已经有代理,也可能这次并不想写。未经询问不要生成代理代码。
  4. 用户已有代理,或明确要求写一个之后,agent 的 base URL 指到代理,不指到 modelfold.ai。
  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=…
export ANTHROPIC_DEFAULT_SONNET_MODEL=…
export ANTHROPIC_DEFAULT_OPUS_MODEL=…
export ANTHROPIC_DEFAULT_HAIKU_MODEL=…

这里的四个模型变量都要使用代理支持的 GET /openai/v1/models 中的 id,而非上面的 Claude id 或内置别名;每个 … 都要替换。

把规则用到 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 还指着 modelfold.ai,一边发另一份 listing 里的 id;也不要把 agent 直接指到模型那一侧的 ModelFold 前缀而不经翻译。

本 skill 不提供什么 ​

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

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