Freeride OpenCode

Configure OpenCode Zen free models with intelligent fallbacks to optimize costs while maintaining reliability.

> ⚠️ Important: To use this skill, you need two API keys:

> 1. OpenCode Zen API key - For OpenCode free models (MiniMax M2.1, Kimi K2.5, GLM 4.7, GPT 5 Nano)

> 2. OpenRouter API key - For OpenRouter free models (Trinity Large and other OpenRouter providers)

>

> Configure both keys in your OpenCode/Zen settings before applying these configurations.

Quick Start

Apply optimal free model configuration with provider diversification:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "opencode/minimax-m2.1-free",
        "fallbacks": [
          "openrouter/arcee-ai/trinity-large-preview:free",
          "opencode/kimi-k2.5-free"
        ]
      },
      "heartbeat": {
        "model": "opencode/glm-4.7-free"
      },
      "subagents": {
        "model": "opencode/kimi-k2.5-free"
      }
    }
  }
}

🔑 API Keys Required

This skill uses models from two different providers, so you need both API keys configured:

1. OpenCode Zen API Key

Required for:

• opencode/minimax-m2.1-free
• opencode/kimi-k2.5-free
• opencode/glm-4.7-free
• opencode/gpt-5-nano

Where to get: Sign up at OpenCode Zen and generate an API key.

2. OpenRouter API Key

Required for:

• openrouter/arcee-ai/trinity-large-preview:free
• Any other OpenRouter free models you add

Where to get: Sign up at OpenRouter.ai and generate an API key.

Configuration

Add both keys to your OpenCode configuration:

{
  "providers": {
    "opencode": {
      "api_key": "YOUR_OPENCODE_ZEN_API_KEY"
    },
    "openrouter": {
      "api_key": "YOUR_OPENROUTER_API_KEY"
    }
  }
}

Fallback Behavior by Provider

• If OpenCode models fail → tries next OpenCode fallback or OpenRouter model
• If OpenRouter models fail → tries next OpenRouter or OpenCode fallback
• Configure both providers for maximum reliability

Model Selection Guide

See models.md for detailed model comparisons, capabilities, and provider information.

Free Models Available

Fallback Strategy

Provider Diversification (v1.2.0)

This version implements provider diversification to maximize resilience against rate limits and service disruptions:

"fallbacks": [
  "openrouter/arcee-ai/trinity-large-preview:free",  // Different provider (OpenRouter)
  "opencode/kimi-k2.5-free"                           // Same provider as primary (OpenCode)
]

Why Provider Diversification Matters:

• Rate limit isolation: If OpenCode experiences rate limits, OpenRouter models remain available (and vice versa)
• First fallback from different provider: Trinity Large on OpenRouter ensures continuity even if all OpenCode models are rate-limited
• Maximum resilience: By spreading across providers, you avoid a single point of failure

Fallback triggers:

• Rate limits exceeded
• Auth failures
• Timeouts
• Provider unavailability

Fallback Behavior by Provider

• If OpenCode models fail → tries OpenRouter fallback first (Trinity Large), then back to OpenCode (Kimi)
• If OpenRouter model fails → tries OpenCode fallback (Kimi)
• This cross-provider approach ensures at least one model is usually available

Per-Task Configuration

Heartbeat (Every 30 min)

"heartbeat": {
  "every": "30m",
  "model": "opencode/gpt-5-nano"
}

Use the cheapest model for frequent, lightweight checks.

Subtasks/Subagents

"subagents": {
  "model": "opencode/kimi-k2.5-free"
}

Good balance for secondary tasks that need reasonable capability.

Complete Example

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "opencode/minimax-m2.1-free",
        "fallbacks": [
          "openrouter/arcee-ai/trinity-large-preview:free",
          "opencode/kimi-k2.5-free"
        ]
      },
      "models": {
        "opencode/minimax-m2.1-free": { "alias": "MiniMax M2.1" },
        "opencode/kimi-k2.5-free": { "alias": "Kimi K2.5" },
        "openrouter/arcee-ai/trinity-large-preview:free": { "alias": "Trinity Large" }
      },
      "heartbeat": {
        "every": "30m",
        "model": "opencode/glm-4.7-free"
      },
      "subagents": {
        "model": "opencode/kimi-k2.5-free"
      }
    }
  }
}

Applying Configuration

Use OpenClaw CLI:

openclaw config.patch --raw '{
  "agents": {
    "defaults": {
      "model": {
        "primary": "opencode/minimax-m2.1-free",
        "fallbacks": ["openrouter/arcee-ai/trinity-large-preview:free", "opencode/kimi-k2.5-free"]
      },
      "heartbeat": { "model": "opencode/glm-4.7-free" },
      "subagents": { "model": "opencode/kimi-k2.5-free" }
    }
  }
}'

Best Practices

1. Provider diversification - Always have your first fallback from a different provider (e.g., OpenRouter) to avoid rate limits affecting all models
2. Keep fallbacks minimal - 2-3 well-chosen fallbacks are better than many
3. Match model to task - Don't use MiniMax for simple checks
4. Test fallback order - Put more capable models first, with provider diversification
5. Monitor usage - Track which models get used most

Troubleshooting

Authentication errors (401/403)?

• Check that you have both API keys configured:
• OpenCode Zen API key for OpenCode models
• OpenRouter API key for Trinity Large and OpenRouter models
• Verify keys are valid and have not expired

Rate limits still occurring?

• Add provider diversification (ensure first fallback is from different provider)
• Consider reducing heartbeat frequency

Responses too slow?

• Move GPT 5 Nano higher in fallback chain
• Use simpler model for subtasks

Model not available?

• Check model ID format: opencode/model-id-free or openrouter/provider/model:free
• Verify model is still free (check models.md)
• Ensure you have the correct API key for the provider

OpenRouter models not working?

• Verify OpenRouter API key is configured
• Check OpenRouter account has credits/access
• Some models may have additional access requirements

References

models.md

Complete reference of all free models with capabilities, providers, performance comparisons, and error handling.

templates.md

Ready-to-use configuration templates for different use cases (minimal, complete, cost-optimized, performance-optimized).

examples/usage.md

Practical examples showing how to use this skill in real scenarios.