Freeride Opencode

Configure and optimize OpenCode Zen free models with smart fallbacks for subtasks, heartbeat, and cron jobs. Use when setting up cost-effective AI model routing with automatic failover between free models.

Security Scan

The skill's documentation asks you to configure and use two provider API keys and CLIs, but the registry metadata does not declare any required credentials or binaries — this mismatch is unexplained and worth investigating before installing.

Purpose & Capability

SKILL.md clearly requires using the OpenClaw and Opencode CLIs and two API keys (OpenCode Zen and OpenRouter) to configure model routing, but the registry metadata lists no required binaries and no required environment variables/credentials. Legitimately, this skill would need the 'openclaw' and probably 'opencode' CLIs and the provider API keys; the omission in metadata is an incoherence that increases risk.

Instruction Scope

Instructions are documentation-only and limited to applying configuration via 'openclaw config.patch', running 'opencode models', editing '~/.openclaw/openclaw.json', and restarting the gateway. Those actions are consistent with a configuration helper, but they modify agent configuration files and assume presence of specific CLIs and configuration storage — the skill instructs actions that affect local agent state and could be used to change routing or endpoint behavior, so review any config changes before applying.

Install Mechanism

There is no install spec and no code files to execute; the skill is instruction-only, which limits the attack surface because nothing new is downloaded or written by the skill itself.

Credentials

SKILL.md explicitly requires two API keys (OpenCode Zen and OpenRouter), but the registry/skill metadata declares no required environment variables or primary credential. That mismatch is the main proportionality problem — the skill expects sensitive credentials but does not declare them, so automatic vetting or principle-of-least-privilege controls can't be applied easily.

Persistence & Privilege

The skill is not always-enabled and uses normal autonomous invocation defaults. It instructs making persistent changes to OpenClaw configuration (editing ~/.openclaw/openclaw.json and restarting the gateway), which is within scope for a config tool but does grant the skill the ability to recommend changes that persist across runs — review those changes before applying. There is no explicit request to modify other skills or system-wide credentials.

What to consider before installing

Don't install blindly. The skill's docs require two API keys and the 'openclaw'/'opencode' CLIs, but the registry metadata doesn't list those dependencies or credentials — ask the publisher why metadata omits required keys and which exact binaries are needed. If you proceed, do these precautions: (1) manually review any JSON the skill suggests before running openclaw config.patch; (2) prefer to apply configuration changes yourself rather than giving the skill automated authority; (3) store API keys with least privilege and confirm where the keys will be placed (OpenClaw settings or a config file) and who/what can read them; (4) test changes in a sandbox or non-production agent first; (5) verify the model IDs and providers independently (OpenRouter models may require separate access). If the publisher cannot explain the metadata omissions, treat the skill as higher risk and avoid installing.

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.

Task Type	Recommended Model	Rationale
Primary/General	MiniMax M2.1 Free	Best free model capability
Fallback 1	Trinity Large Free	Different provider (OpenRouter) for rate limit resilience
Fallback 2	Kimi K2.5 Free	General purpose, balance
Heartbeat	GLM 4.7 Free	Multilingual, cost-effective for frequent checks
Subtasks/Subagents	Kimi K2.5 Free	Balanced capability for secondary tasks

Free Models Available

Model	ID	Best For
MiniMax M2.1 Free	opencode/minimax-m2.1-free	Complex reasoning, coding (Primary)
Trinity Large Free	openrouter/arcee-ai/trinity-large-preview:free	High-quality OpenRouter option (Fallback 1)
Kimi K2.5 Free	opencode/kimi-k2.5-free	General purpose, balance (Fallback 2)

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.