Troubleshooting
Common problems when using the ModelFold skills, and how to fix them.
For agent-specific issues, each agent page (Claude Code, Codex CLI, Grok Build) also has its own Common pitfalls list.
Installation and API key
| Symptom | Cause / Fix |
|---|---|
npx: command not found | Node.js is not installed. Install Node.js, then run npx skills add https://ai.modelfold.online/ again. |
| The agent doesn't seem to use the skill | Restart the agent after installing. You can also name the skill in your request: "Use the modelfold-models skill to …". |
The agent says MODELFOLD_API_KEY is missing | The variable is not set in the shell that started the agent. Export it, then restart the agent from that same shell. |
401 Unauthorized | The key is wrong or expired, or it was sent in the wrong header. ModelFold only accepts Authorization: Bearer <key>; a header named apikey is rejected. Check your key at ai.modelfold.online/api-key. |
| Windows: the variable still isn't picked up | setx only affects windows opened afterwards. Close every terminal, including those inside VS Code, Cursor and other editors, and reopen. Or set $env:MODELFOLD_API_KEY in the current window. |
PowerShell: curl rejects the arguments | In PowerShell curl is an alias for Invoke-WebRequest. Use curl.exe. |
jq: command not found | Install it: brew install jq, apt install jq or winget install jqlang.jq. |
Running models (modelfold-models)
| Symptom | Cause / Fix |
|---|---|
| The agent picked a different model than you wanted | Name the model in your request, for example "with GPT Image 2". |
| The task failed | Read error.message in the response, or check your request history in the console; failed jobs are refunded automatically. Ask the agent to retry with adjusted parameters. |
| Not enough credits | Top up on ai.modelfold.online/pricing, then ask the agent to run the task again. |
| A result link no longer opens | If the result URL is relative (/uploads/outputs/…), prefix it with https://ai.modelfold.online. Ask the agent to save results to a local path so you keep a copy. |
Chat agents (modelfold-chat-agents)
| Symptom | Cause / Fix |
|---|---|
| Requests fail or behave oddly after connecting to an agent | The model may be an older version that supports chat only (marked "Chat only" on its model page). Switch to the latest model in that series. |
model not found | The model name is not in that agent's listing. List models from the agent's endpoint (/anthropic/v1/models, /openai/v1/models or /xai/v1/models) and use an id from it. |
Request path doubled, such as /v1/v1/messages or /responses/responses | The base URL contains the full request URL. Each agent appends its own suffix; remove it from the base URL. |
| Claude Code asks you to log in to an Anthropic account | The environment variables are not in that process. Fully quit the terminal and reopen from a shell where they are exported. |
| Codex or Grok Build ignores your provider | The provider is in a project-level config file. Move it to ~/.codex/config.toml or ~/.grok/config.toml. |
| You want to use a model from another vendor's protocol | The agent and the model speak different protocols. See When protocols don't match on the Install modelfold-chat-agents page. |
Debugging
- Claude Code:
claude --debugprints the requests it sends. - Codex CLI:
codex doctorreports the loaded config and whether the provider is reachable. - Grok Build:
RUST_LOG=debug GROK_LOG_FILE=/tmp/grok.log grokwrites a request trace. - Every ModelFold call shows up on console.
Still stuck? Contact support@modelfold.online.