OpenCode API Key Integration Guide

This guide explains how to connect your OpenLLM API Key to OpenCode, enabling OpenCode to access and use models provided through the OpenLLM platform, including OpenAI.

1. Integration Principle

OpenCode uses an AI SDK Provider mechanism, allowing you to connect to any OpenAI Compatible API.

The official recommended approach for connecting OpenLLM:

Use a Custom Provider
Provide your OpenLLM API Key
Communicate via OpenAI Compatible SDK with the OpenLLM API

Workflow

OpenCode
    ↓
Custom Provider
    ↓
OpenLLM API
    ↓
GPT-5.5 / etc.

2. Obtain Your OpenLLM API Key

Log in to the OpenLLM console: https://openllm.dev
Open the API Keys page
Create a new API Key, for example:

sk-xxxxxxxxxxxxxxxxxxxxxxxx

⚠️ Keep your API Key secure and do not expose it publicly.

3. Add OpenLLM Credentials in OpenCode (Optional)

If your OpenCode version supports the /connect command for custom providers:

/connect

Select Other
Enter Provider ID: openllm
Enter your OpenLLM API Key

For cross-version compatibility, it is recommended to use a configuration file (see sections 4 and 5).

4. Create a Provider Configuration File

OpenCode supports both global and project-level configurations:

Global Configuration (applies to multiple projects):
~/.config/opencode/opencode.json
Project Configuration (recommended):
<Project Root>/opencode.json

5. Official Recommended Configuration (OpenLLM + GPT-5.5)

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openllm": {
      "npm": "@ai-sdk/openai",
      "name": "OpenLLM",
      "options": {
        "baseURL": "https://api.openllm.dev/v1",
        "apiKey": "{env:OPENLLM_API_KEY}"
      }
    }
  },
  "model": "openllm/gpt-5.5"
}

Notes

npm must be @ai-sdk/openai to ensure the OpenAI Compatible SDK works correctly
baseURL should be set to the OpenLLM API endpoint provided in the console
apiKey can use {env:OPENLLM_API_KEY} for environment variable management
model can be replaced with any OpenLLM-supported model, e.g., openllm/gpt-5.5

6. Set Environment Variable (Optional)

Linux / macOS

export OPENLLM_API_KEY="sk-xxxxxxxxxxxxxxxx"

Windows PowerShell

$env:OPENLLM_API_KEY="sk-xxxxxxxxxxxxxxxx"

Using environment variables avoids manually entering API keys via /connect, enhancing security.

7. Start OpenCode and Initialize Project

cd my-project
opencode
/init

/init automatically analyzes the project structure and prepares the model environment
After initialization, OpenCode can directly call OpenLLM models

8. Switch and Use Models

List Available Models

/models

Select Model

openllm/gpt-5.5

You are now ready to use OpenLLM GPT-5.5 services.

9. Common Issues

Issue	Cause	Solution
401 Unauthorized	Invalid API Key	Verify the API Key in `/connect` or environment variable
Model Not Found	Incorrect model ID	Ensure the `model` field matches OpenLLM’s model ID exactly (e.g., `openllm/gpt-5.5`)
Cannot Connect to API	Incorrect endpoint	Check `options.baseURL` matches the endpoint shown in the console
OpenCode Does Not Recognize Configuration	Invalid file path or JSON	Verify `~/.config/opencode/opencode.json` or `<Project Root>/opencode.json` exists and is valid

10. Official Template (Final Version)

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openllm": {
      "npm": "@ai-sdk/openai",
      "name": "OpenLLM",
      "options": {
        "baseURL": "https://api.openllm.dev/v1",
        "apiKey": "{env:OPENLLM_API_KEY}"
      }
    }
  },
  "model": "openllm/gpt-5.5"
}

✅ At this point, OpenCode has successfully integrated with the OpenLLM API and can directly call GPT-5.5 and other OpenLLM models.