Skillintermediate

OpenCode Quickstart

import Image from '@theme/IdealImage'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Claude Code Knowledge Pack7/10/2026

Overview

OpenCode Quickstart

This tutorial shows how to connect OpenCode to your existing LiteLLM instance and switch between models.

:::info

This integration allows you to use any LiteLLM supported model through OpenCode with centralized authentication, usage tracking, and cost controls.

:::

<br />

Video Walkthrough

Prerequisites

LiteLLM already configured and running (e.g., http://localhost:4000)
LiteLLM API key

Installation

Step 1: Install OpenCode

Choose your preferred installation method:

curl -fsSL https://opencode.ai/install | bash

npm install -g opencode-ai

brew install sst/tap/opencode

Verify installation:

opencode --version

Step 2: Configure LiteLLM Provider

Create your OpenCode configuration file. You can place this in different locations depending on your needs:

Configuration locations:

Global: ~/.config/opencode/opencode.json (applies to all projects)
Project: opencode.json in your project root (project-specific settings)
Custom: Set OPENCODE_CONFIG environment variable

Create ~/.config/opencode/opencode.json (global config):

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "litellm": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LiteLLM",
      "options": {
        "baseURL": "http://localhost:4000/v1"
      },
      "models": {
        "gpt-4": {
          "name": "GPT-4"
        },
        "claude-3-5-sonnet-20241022": {
          "name": "Claude 3.5 Sonnet"
        },
        "deepseek-chat": {
          "name": "DeepSeek Chat"
        }
      }
    }
  }
}

:::tip The keys in the "models" object (e.g., "gpt-4", "claude-3-5-sonnet-20241022") should match the model_name values from your LiteLLM configuration. The "name" field provides a friendly display name that will appear as an alias in OpenCode. :::

Step 3: Connect to LiteLLM Provider

Launch OpenCode:

opencode

Add your API key:

/connect

Then:

Enter provider name: LiteLLM (must match the "name" field in your config)
Enter your LiteLLM API key: Your LiteLLM master key or virtual key

Step 4: Switch Between Models

In OpenCode, run:

/models

Select any model from your LiteLLM configuration. OpenCode will route all requests through your LiteLLM instance.

Advanced Configuration

Model Parameters

You can customize model parameters like context limits:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "litellm": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LiteLLM",
      "options": {
        "baseURL": "http://localhost:4000/v1"
      },
      "models": {
        "gpt-4": {
          "name": "GPT-4",
          "limit": {
            "context": 128000,
            "output": 4096
          }
        },
        "claude-3-5-sonnet-20241022": {
          "name": "Claude 3.5 Sonnet",
          "limit": {
            "context": 200000,
            "output": 8192
          }
        }
      }
    }
  }
}

Multi-Provider Setup

You can configure multiple LiteLLM instances or mix with other providers:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "litellm-prod": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LiteLLM Production",
      "options": {
        "baseURL": "https://your-prod-instance.com/v1"
      },
      "models": {
        "gpt-4": {
          "name": "GPT-4 (Production)"
        }
      }
    },
    "litellm-dev": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LiteLLM Development",
      "options": {
        "baseURL": "http://localhost:4000/v1"
      },
      "models": {
        "gpt-4": {
          "name": "GPT-4 (Development)"
        }
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "litellm": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LiteLLM",
      "options": {
        "baseURL": "http://localhost:4000/v1"
      },
      "models": {
        "gpt-4": {
          "name": "GPT-4 via LiteLLM"
        },
        "claude-3-5-sonnet-20241022": {
          "name": "Claude 3.5 Sonnet via LiteLLM"
        }
      }
    },
    "openai": {
      "npm": "@ai-sdk/openai",
      "name": "OpenAI Direct",
      "models": {
        "gpt-4o": {
          "name": "GPT-4o (Direct)"
        }
      }
    }
  }
}

Example LiteLLM Configuration

Here's an example LiteLLM config.yaml that works well with OpenCode:

model_list:
  # OpenAI models
  - model_name: gpt-4
    litellm_params:
      model: openai/gpt-4
      api_key: os.environ/OPENAI_API_KEY

  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY

  # Anthropic models
  - model_name: claude-3-5-sonnet-20241022
    litellm_params:
      model: anthropic/claude-3-5-sonnet-20241022
      api_key: os.environ/ANTHROPIC_API_KEY

  # DeepSeek models
  - model_name: deepseek-chat
    litellm_params:
      model: deepseek/deepseek-chat
      api_key: os.environ/DEEPSEEK_API_KEY

Dropping OpenCode-specific parameters

OpenCode sends a reasoningSummary parameter with reasoning-capable models such as gpt-5. This parameter is not supported by the Chat Completions API and will cause errors. Add additional_drop_params to every model entry in your model_list that will receive requests from OpenCode with reasoning enabled:

model_list:
  - model_name: gpt-5
    litellm_params:
      model: openai/gpt-5
      api_key: os.environ/OPENAI_API_KEY
      additional_drop_params: ["reasoningSummary"]

Troubleshooting

OpenCode not connecting:

Verify your LiteLLM proxy is running: curl http://localhost:4000/health
Check that the baseURL in your OpenCode config matches your LiteLLM instance
Ensure the provider name in /connect matches exactly with your config

Authentication errors:

Verify your LiteLLM API key is correct
Check that your LiteLLM instance has authentication properly configured
Ensure your API key has access to the models you're trying to use

Model not found:

Ensure the model names in OpenCode config match your LiteLLM model_name values
Check LiteLLM logs for detailed error messages
Verify the models are properly configured in your LiteLLM instance

Configuration not loading:

Check the config file path and permissions
Validate JSON syntax using a JSON validator
Ensure the $schema URL is accessible

Unknown parameter: 'reasoningSummary' error:

OpenCode sends a reasoningSummary parameter that is not supported by the Chat Completions API. Add additional_drop_params: ["reasoningSummary"] to each affected model entry in your litellm_params:
```
- model_name: gpt-5
  litellm_params:
    model: openai/gpt-5
    api_key: os.environ/OPENAI_API_KEY
    additional_drop_params: ["reasoningSummary"]
```

Tips

Add more models to the config as needed - they'll appear in /models
Use project-specific configs for different codebases with different model requirements
Monitor your LiteLLM proxy logs to see OpenCode requests in real-time