Justinaquino: "Add OpenCode Multi-Provider Configuration Guide wiki entry"

2026-03-31T16:40:51Z

"Add OpenCode Multi-Provider Configuration Guide wiki entry"

New page

= OpenCode Multi-Provider Configuration Guide =

'''Date:''' 2026-04-01<br>
'''Author:''' Justin / Comfac IT / CGG R&D & BD<br>
'''Status:''' 📋 Reference Configuration<br>
'''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 (<code>kimi-for-coding</code>) via Kimi API
* '''Local''': Multiple Qwen models via Ollama (running in Distrobox)

{{mbox | type = warning | text = ⚠️ '''Critical Note''': This setup runs inside a '''Distrobox container''' with a custom home directory mapping (non-standard <code>$HOME</code> location). All paths in this config are relative to that mapped directory.}}

----

== Architecture Overview ==

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

'''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 (<code>[defaults]</code>) ===

<pre>
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
</pre>

{{mbox | type = warning | text = ⚠️ '''Critical''': <code>default_yolo = false</code> is recommended for production code. Set to <code>true</code> only for fully automated workflows.}}

----

=== 2. Managed Provider: Kimi ===

<pre>
[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"]
</pre>

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

{{mbox | type = notice | text = 💡 '''Distrobox Note''': Since home is remapped, OAuth tokens persist in your chosen directory, not <code>~/.config</code>.}}

----

=== 3. Local Provider: Ollama ===

You have '''6 local models''' configured covering different use cases:

{| class="wikitable"
! Model !! Size !! Context !! Best For
|-
| <code>qwen3.5-4b</code> || 4B || 131k || Quick tasks, low latency
|-
| <code>qwen3.5-9b</code> || 9B || 131k || General coding, reasoning
|-
| <code>qwen3.5-9b-instruct</code> || 9B || 32k || Instruction following
|-
| <code>qwen2.5-coder-7b</code> || 7B || 32k || Code-specific tasks
|-
| <code>qwen3-vl-2b</code> || 2B || 32k || Vision + coding
|-
| <code>qwen3-vl-grammar</code> || - || 32k || Grammar/validation tasks
|}

<pre>
[providers.ollama]
type = "openai_legacy"
base_url = "http://localhost:11434/v1"
api_key = "ollama"
</pre>

{{mbox | type = notice | text = 💡 '''Distrobox Networking''': <code>localhost:11434</code> refers to the container's localhost. Ensure Ollama is running inside the same Distrobox or exposed to the container.}}

----

=== 4. Loop Control (<code>[loop_control]</code>) ===

<pre>
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
</pre>

'''Tuning Tips''':
* Increase <code>max_steps_per_turn</code> for complex refactoring (risk: higher API costs)
* Lower <code>compaction_trigger_ratio</code> to 0.75 if working with very large files
* <code>reserved_context_size</code> prevents context overflow crashes

----

=== 5. Background Processing (<code>[background]</code>) ===

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

{{mbox | type = notice | text = 💡 '''Distrobox Consideration''': Background tasks write to the mapped home directory. Ensure sufficient disk space in that location.}}

----

=== 6. Moonshot Services (<code>[services.*]</code>) ===

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

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

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

----

=== 7. MCP Client Settings (<code>[mcp.client]</code>) ===

<pre>
[mcp.client]
tool_call_timeout_ms = 60000 # 60 second timeout for tools
</pre>

{{mbox | type = notice | text = 💡 '''Important''': When using Kimi as an MCP for local models, this timeout applies to operations triggered by the local model via Kimi's tools.}}

----

== Advanced Usage Patterns ==

=== Pattern 1: Kimi as MCP Server for Local Models ===

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

'''Setup''':
# Configure your MCP client (Claude/OpenCode/Aider) to point to this config
# Set <code>default_model</code> to an Ollama model in the client
# The client can still invoke Kimi's tools (search, fetch) via the MCP bridge

'''Config Override''':
<pre>
# Temporarily switch to local
default_model = "qwen3.5-9b"
default_thinking = true # Qwen supports thinking
</pre>

----

=== Pattern 2: Distrobox Path Mapping ===

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

<pre>
# 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
</pre>

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

----

=== Pattern 3: Model Switching Workflows ===

<pre>
# 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"
</pre>

'''Command Palette''' (if your client supports it):
* <code>/model kimi-code/kimi-for-coding</code> — Cloud, full capabilities
* <code>/model qwen3.5-9b</code> — Local, private, reasoning
* <code>/model qwen3-vl-2b</code> — Vision tasks with local image analysis

----

== Distrobox-Specific Configuration ==

=== Volume Mounts Checklist ===

Ensure your Distrobox creation included:
<pre>
distrobox create --name ai-dev \
--home /mnt/projects/ai-home \ # Matches your config
--additional-flags "--volume /mnt/projects:/mnt/projects"
</pre>

----

=== Ollama Inside Distrobox ===

If Ollama runs in the same container:
<pre>
# Start Ollama before the MCP client
ollama serve & # Binds to localhost:11434 inside container

# Verify models are available
ollama list | grep qwen
</pre>

----

=== Persisting OAuth Tokens ===

Since home is custom, tokens survive container recreation:
<pre>
# Backup
tar czf oauth-backup.tar.gz $HOME/oauth/

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

----

== Security & Best Practices ==

# '''API Keys''': Empty strings in config (<code>api_key = ""</code>) indicate OAuth-only. Never hardcode keys in the TOML file.
# '''YOLO Mode''': Keep <code>default_yolo = false</code> unless running in a fully containerized/throwaway environment.
# '''Context Window''': The 256k context for Kimi vs 32k/131k for local models — be mindful when switching contexts.
# '''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''':
<pre>
# 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
</pre>

----

=== Issue: OAuth token not found ===

'''Cause''': Wrong home directory mapping

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

----

=== Issue: Context overflow with local models ===

'''Cause''': <code>max_context_size</code> mismatch

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

----

== Quick Reference: Model Selection ==

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

----

== See Also ==

* [[OpenCoder Qwen35 Agentic Setup 260330]] — Qwen3.5 Modelfile fix for tool calling
* [[Project OpenCoder: AI Independence Initiative]] — Strategic roadmap
* [[Proceedural Agentic Development Methodology 260304]] — PAD methodology
* [[Opencode isolation and burner workflow 260216]] — Distrobox burner workflow
* [[Ollama GNOME System Tray Panel 260401]] — Ollama system tray toggle
* [[🧠 Process: Selecting and Installing the Right Ollama Model for Your Hardware]] — Model selection guide

[[Category:AI]]
[[Category:OpenCode]]
[[Category:Ollama]]
[[Category:Tutorials]]
[[Category:Comfac IT]]

OpenCode Multi-Provider Configuration Guide 260401 - Revision history

Justinaquino: "Add OpenCode Multi-Provider Configuration Guide wiki entry"