Jump to content

OpenCode Multi-Provider Configuration Guide 260401

From MediawikiCIT
Revision as of 16:40, 31 March 2026 by Justinaquino (talk | contribs) ("Add OpenCode Multi-Provider Configuration Guide wiki entry")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

OpenCode Multi-Provider Configuration Guide

Date: 2026-04-01
Author: Justin / Comfac IT / CGG R&D & BD
Status: 📋 Reference Configuration
Related: OpenCoder Qwen35 Agentic Setup 260330, Project OpenCoder: AI Independence Initiative

Overview

This configuration enables a dual-mode AI coding environment:

  • Cloud: Kimi's managed models (kimi-for-coding) via Kimi API
  • Local: Multiple Qwen models via Ollama (running in Distrobox)

Template:Mbox

Architecture Overview

┌─────────────────────────────────────────┐
│           MCP Client (Host)             │
│  ┌──────────────┐    ┌──────────────┐  │
│  │ Kimi Managed │    │ Local Ollama │  │
│  │  (Cloud API) │    │  (Container) │  │
│  └──────────────┘    └──────────────┘  │
└─────────────────────────────────────────┘
           │
    ┌──────┴──────┐
    ▼             ▼
[Claude]  [OpenCode]  [Aider]  [Qwen]
   MCP        MCP       MCP      MCP

Key Feature: You can use Kimi as an MCP server to power other MCP clients (Claude Desktop, OpenCode, Aider, etc.) while leveraging local models.

Configuration Sections

1. Default Behavior ([defaults])

default_model = "kimi-code/kimi-for-coding"
default_thinking = true        # Enable reasoning/thinking tokens
default_yolo = false          # Require confirmation for destructive ops
default_editor = ""           # Auto-detect editor

Template:Mbox

2. Managed Provider: Kimi

[models."kimi-code/kimi-for-coding"]
provider = "managed:kimi-code"
model = "kimi-for-coding"
max_context_size = 262144     # 256k context window
capabilities = ["thinking", "image_in", "video_in"]

Key Points:

  • Context Size: 262144 tokens (256k) — suitable for large codebases
  • Capabilities:
    • thinking: Reasoning/research mode
    • image_in: Screenshot/UI analysis
    • video_in: Video processing (if supported)
  • OAuth Storage: Credentials stored in oauth/kimi-code (relative to mapped home)

Template:Mbox

3. Local Provider: Ollama

You have 6 local models configured covering different use cases:

Model Size Context Best For
qwen3.5-4b 4B 131k Quick tasks, low latency
qwen3.5-9b 9B 131k General coding, reasoning
qwen3.5-9b-instruct 9B 32k Instruction following
qwen2.5-coder-7b 7B 32k Code-specific tasks
qwen3-vl-2b 2B 32k Vision + coding
qwen3-vl-grammar - 32k Grammar/validation tasks 
[providers.ollama]
type = "openai_legacy"
base_url = "http://localhost:11434/v1"
api_key = "ollama"

Template:Mbox

4. Loop Control ([loop_control])

max_steps_per_turn = 100           # Max operations per request
max_retries_per_step = 3           # Retry failed operations
max_ralph_iterations = 0             # Legacy/compatibility setting
reserved_context_size = 50000        # Reserve 50k tokens for system
compaction_trigger_ratio = 0.85      # Compact memory at 85% usage

Tuning Tips:

  • Increase max_steps_per_turn for complex refactoring (risk: higher API costs)
  • Lower compaction_trigger_ratio to 0.75 if working with very large files
  • reserved_context_size prevents context overflow crashes

5. Background Processing ([background])

max_running_tasks = 4               # Parallel background operations
read_max_bytes = 30000              # 30KB file read limit
notification_tail_lines = 20        # Lines in status notifications

Template:Mbox

6. Moonshot Services ([services.*])

[services.moonshot_search]
base_url = "https://api.kimi.com/coding/v1/search"

[services.moonshot_fetch]
base_url = "https://api.kimi.com/coding/v1/fetch"

These enable web search and URL fetching capabilities within the Kimi ecosystem. OAuth credentials are shared with the main provider.

7. MCP Client Settings ([mcp.client])

[mcp.client]
tool_call_timeout_ms = 60000        # 60 second timeout for tools

Template:Mbox

Advanced Usage Patterns

Pattern 1: Kimi as MCP Server for Local Models

Scenario: You want to use qwen3.5-9b (local) for code generation, but leverage Kimi's search/fetch tools.

Setup:

  1. Configure your MCP client (Claude/OpenCode/Aider) to point to this config
  2. Set default_model to an Ollama model in the client
  3. The client can still invoke Kimi's tools (search, fetch) via the MCP bridge

Config Override: 

# Temporarily switch to local
default_model = "qwen3.5-9b"
default_thinking = true  # Qwen supports thinking

Pattern 2: Distrobox Path Mapping

Since your home is remapped (e.g., /mnt/projects/ai-home instead of /home/user): 

# OAuth paths are relative to the mapped home
[providers."managed:kimi-code".oauth]
storage = "file"
key = "oauth/kimi-code"  # Resolves to /mnt/projects/ai-home/oauth/kimi-code

Verification: 

# Inside Distrobox
echo $HOME                    # Should show /mnt/projects/ai-home (or your mapping)
ls $HOME/oauth/kimi-code      # Should contain OAuth tokens

Pattern 3: Model Switching Workflows

# High-level architecture discussion
default_model = "kimi-code/kimi-for-coding"

# Quick local edits (low latency)
alias_model = "qwen3.5-4b"

# Complex reasoning (local, private)
secure_model = "qwen3.5-9b"

Command Palette (if your client supports it):

  • /model kimi-code/kimi-for-coding — Cloud, full capabilities
  • /model qwen3.5-9b — Local, private, reasoning
  • /model qwen3-vl-2b — Vision tasks with local image analysis

Distrobox-Specific Configuration

Volume Mounts Checklist

Ensure your Distrobox creation included: 

distrobox create --name ai-dev \
  --home /mnt/projects/ai-home \          # Matches your config
  --additional-flags "--volume /mnt/projects:/mnt/projects"

Ollama Inside Distrobox

If Ollama runs in the same container: 

# Start Ollama before the MCP client
ollama serve &  # Binds to localhost:11434 inside container

# Verify models are available
ollama list | grep qwen

Persisting OAuth Tokens

Since home is custom, tokens survive container recreation: 

# Backup
tar czf oauth-backup.tar.gz $HOME/oauth/

# Restore (new container)
tar xzf oauth-backup.tar.gz -C $HOME/

Security & Best Practices

  1. API Keys: Empty strings in config (api_key = "") indicate OAuth-only. Never hardcode keys in the TOML file.
  2. YOLO Mode: Keep default_yolo = false unless running in a fully containerized/throwaway environment.
  3. Context Window: The 256k context for Kimi vs 32k/131k for local models — be mindful when switching contexts.
  4. Distrobox Isolation: Your remapped home provides natural isolation. Sensitive data stays in your mapped directory, not system home.

Troubleshooting

Issue: "Ollama connection refused"

Cause: Ollama not running or not exposed to Distrobox

Fix: 

# Check if Ollama is listening
curl http://localhost:11434/api/tags

# If using host Ollama from inside Distrobox, use host IP
# Edit base_url to: http://host.docker.internal:11434/v1

Issue: OAuth token not found

Cause: Wrong home directory mapping

Fix: Verify $HOME inside Distrobox matches where you expect oauth/ to live.

Issue: Context overflow with local models

Cause: max_context_size mismatch

Fix: Ensure your prompt + file contents < model's max_context_size (32k for most Qwen models vs 256k for Kimi).

Quick Reference: Model Selection

Task Recommended Model Why
Architecture decisions kimi-code/kimi-for-coding 256k context, reasoning
Quick bug fixes qwen3.5-4b Fast, sufficient context
Complex refactoring qwen3.5-9b (131k) Large context, private
Image → Code qwen3-vl-2b Vision capabilities, local
Documentation qwen2.5-coder-7b Code-optimized, offline

See Also

Retrieved from "https://mediawiki.comfac.net/index.php?title=OpenCode_Multi-Provider_Configuration_Guide_260401&oldid=213"