安装 Skill
首次会话积分消耗偏高属正常现象
Agent 每次请求都会携带固定的工具定义和系统提示(通常有数万 token)。首次会话这部分内容需要写入缓存,按全量输入计费,所以消耗的积分会比较多;之后的请求命中缓存,这部分按低价缓存计费,消耗会明显下降。这是正常现象,并非多扣费。如有大量使用需求,请联系客服,我们可提供优惠。
ModelFold 提供两个 skill,装上后 Agent 就知道怎么用 ModelFold:
| skill | 装上之后 |
|---|---|
modelfold-models | 让 Agent 生成图片、视频、语音,调用对话模型 |
modelfold-chat-agents | 让 Agent 自动把 Claude Code、Codex、Grok Build 配到 ModelFold |
一条命令装好两个
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
在终端里运行。这条命令可以整段复制,不会停下来提问:
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。在项目目录里运行:
npx skills add https://modelfold.ai --skill modelfold-models -a cursor -y需要在 Cursor 里手动填模型 ID 时,从 全部模型 ID 复制。
技能在该项目的 .agents/skills/modelfold-models。
想在所有项目里给 Cursor 用,全局安装之后再补软链:
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):
export MODELFOLD_API_KEY=your_keyWindows(PowerShell)
$env:MODELFOLD_API_KEY = "your_key"
setx MODELFOLD_API_KEY "your_key"setx 只对之后新开的窗口生效。想立刻用上,同时设 $env:。
第 3 步:试一下
在已设置 MODELFOLD_API_KEY 的 shell 里重启 Agent,然后直接用自然语言提需求:
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 的模型列表为准。
安装
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> 上创建的 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 为准。
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-5PowerShell 和 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 共同的规则:
- 模型名从 listing 里取,不要凭记忆写。 每次都重新跑 listing,模型集合会变。
- 用
Authorization: Bearer认证。 名字就叫apikey的请求头会被 401 拒掉。 - base URL 不要写完整请求 URL。 Agent 会自己往后拼
/v1/messages或/responses。 - 配置写进用户级文件,不要写进项目级文件。 项目级文件要么被忽略,要么会被提交进仓库。
协议不一致时
本 skill 里每个 agent 说一种 wire 协议,ModelFold 的每份 listing 也按一种协议提供。两者一致时,按该 agent 那一节配置,流量打到 modelfold.ai。不一致时,需要一个本地翻译代理。
什么时候需要代理
- 读该 agent 那一节:它说什么协议、会往后面拼哪一段。
- 读模型的 listing:ModelFold 按什么协议提供。
- 协议相同:不需要代理。协议不同:告诉用户需要本地翻译代理,并且 动手写之前先问。用户可能已经有代理,也可能这次并不想写。未经询问不要生成代理代码。
- 用户已有代理,或明确要求写一个之后,agent 的 base URL 指到代理,不指到
modelfold.ai。 - 列模型走 模型那一侧 的 listing,不走 agent 原生 listing。agent 的模型配置填那份列表里的 id——它内置的默认名和别名只对原生协议成立。
代理要暴露什么
| 模型 listing | ModelFold 请求 | 协议 |
|---|---|---|
GET /openai/v1/models | POST /openai/v1/responses | Responses |
GET /anthropic/v1/models | POST /anthropic/v1/messages | Messages |
GET /xai/v1/models | POST /xai/v1/responses | Responses |
代理听的是 agent 会拼出来的那条路径,转到 该 listing 对应的 ModelFold 请求。两个方向都要翻译,包括 agent 实际会发的流式和 tool 调用。打到 ModelFold 的鉴权是 Authorization: Bearer $MODELFOLD_API_KEY。
以后新 agent 的 listing 不在这张表里时,加一行即可。这一节的规则不用改。
写代理时
只有用户明确要求时才写。映射要诚实,不要发明平台行为。
- 两种协议的形状从真实 agent 请求和官方协议里学,不要凭记忆填字段。 抓 agent 实际发出的请求(
claude --debug、Codex 日志、GROK_LOG_FILE)和 ModelFold 在模型路径上要的形状。凭训练数据拼出来的字段表通常是残的。 modelid 原样转发。 不要写死默认模型名,也不要把sonnet/opus/claude-*改写成 GPT slug,反过来也不要。- 若代理要接
GET /models,返回的是 agent 期望的列表形状,数据来自模型那一侧的 ModelFold listing。 把另一边的文档原样转过去形状是错的。listing 失败就是错误,不要编一条假模型。 - 工具调用必须能走完一轮。
id/call_id/tool_use_id在请求和下一轮的 tool result 里保持一致。不要丢掉tools。ModelFold 若拒绝 tools,把那个错误传回去。 - 流式必须按 agent 结束一轮的方式收尾。 发出该 agent 会消费的事件序列,包括终态事件。ModelFold 中途报错或断流时,agent 必须看到失败,而不是 HTTP 200 加一轮空的 completed。
- 不要为了绕过协议限制而塞进新的 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 模型:
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 模型:
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 里哪个配置项填代理地址。只有用户明确要求时才写代理代码。
