常见问题排查

使用 ModelFold skill 时的常见问题和解决办法。

各 Agent 特有的问题，另见对应页面（「Claude Code」「Codex CLI」「Grok Build」）里的常见坑。

---

安装与 API Key

现象	原因 / 解决
npx: command not found	没有安装 Node.js。装好后重新运行 npx skills add https://ai.modelfold.online/。
Agent 好像没用上 skill	安装后重启 Agent。也可以在请求里直接点名：“Use the modelfold-models skill to …”。
Agent 提示缺少 MODELFOLD_API_KEY	启动 Agent 的 shell 里没有这个变量。导出后，从同一个 shell 重启 Agent。
401 Unauthorized	Key 错误或已失效，或者放错了请求头。ModelFold 只认 Authorization: Bearer <key>，名为 apikey 的请求头会被拒绝。到 控制台 → API Keys 核对。
Windows 下变量仍然不生效	setx 只对之后新开的窗口生效。关掉所有终端（包括 VS Code、Cursor 等编辑器内置终端）后重开，或在当前窗口设 $env:MODELFOLD_API_KEY。
PowerShell 的 curl 报参数错误	PowerShell 里 curl 是 Invoke-WebRequest 的别名，改用 curl.exe。
jq: command not found	安装 jq：brew install jq、apt install jq 或 winget install jqlang.jq。

---

运行模型（modelfold-models）

现象	原因 / 解决
Agent 选的模型不是你想要的	在请求里点名模型，例如“用 GPT Image 2”。
任务失败	看接口返回的 error.message，或到控制台查看调用记录；失败的任务会自动退款。再让 Agent 调整参数重试。
积分不足	到 ai.modelfold.online/pricing 充值后，让 Agent 重新运行任务。
结果链接打不开了	结果地址如果是 /uploads/outputs/… 这样的相对路径，要补上 https://ai.modelfold.online。建议让 Agent 把结果保存到本地。

---

编程 Agent（modelfold-chat-agents）

现象	原因 / 解决
接入 Agent 后请求报错或结果异常	所用模型可能是仅支持对话调用的较早版本（模型页标有「仅支持对话调用」）。换成该系列的最新版模型。
model not found	模型名不在该 Agent 的 listing 里。从对应接口（/anthropic/v1/models、/openai/v1/models 或 /xai/v1/models）列出模型，填里面的 id。
请求路径重复，例如 /v1/v1/messages 或 /responses/responses	base URL 里写了完整请求 URL。各 Agent 会自己拼后缀，从 base URL 里去掉它。
Claude Code 弹出 Anthropic 账号登录	这个进程里没有环境变量。彻底退出终端，从已导出变量的 shell 里重开。
Codex 或 Grok Build 没用上你配的 provider	provider 写进了项目级配置文件。移到 ~/.codex/config.toml 或 ~/.grok/config.toml。
想用另一种协议的模型	Agent 与模型的协议不一致。见「安装 modelfold-chat-agents」页的协议不一致时一节。

---

调试

• Claude Code：claude --debug 会打印实际发出的请求。
• Codex CLI：codex doctor 会报告加载到的配置以及 provider 是否可达。
• Grok Build：RUST_LOG=debug GROK_LOG_FILE=/tmp/grok.log grok 会写下请求轨迹。
• 每一次对 ModelFold 的调用都能在 控制台 看到。

仍未解决？联系 support@modelfold.online。