References: OpenCode Config, Providers

OpenCode uses the OpenAI Chat Completions API. When connecting to a custom gateway, declare the endpoint and the model list in the provider block of opencode.jsonc.

1. Installation and Configuration File

1

npm install -g opencode-ai

The user configuration is at ~/.config/opencode/opencode.jsonc by default (opencode.json also works).

Configuration precedence (high → low):

1. macOS Managed configuration (pushed by the enterprise, cannot be overridden)
2. Inline configuration OPENCODE_CONFIG_CONTENT
3. Project configuration opencode.json / opencode.jsonc
4. Custom path OPENCODE_CONFIG
5. Global configuration ~/.config/opencode/opencode.jsonc

It is best to keep the Provider and Key in the global configuration, to avoid committing them to git.

2. Connecting to a Gateway

When connecting to an OpenAI-compatible gateway, npm is always @ai-sdk/openai-compatible.

2.1 Minimal Configuration

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "llmapi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "llmapi",
      "options": {
        "baseURL": "https://api.xxx.com/v1",
        "apiKey": "your-token"
      },
      "models": {
        "glm-5.2": { "name": "GLM 5.2" }
      }
    }
  },
  "model": "llmapi/glm-5.2"
}

Restart OpenCode, then use /models in the TUI to confirm whether the model is loaded.

2.2 Where to Put the Secret

Writing apiKey directly in the configuration file leaves it on disk in plaintext. The api.xxx.com and your-token in this post’s examples are placeholders; replace them with your own values, and never commit a real Key to a public repository.

Safer approaches:

"apiKey": "{env:LLMAPI_KEY}"

1

export LLMAPI_KEY=your-token

"apiKey": "{file:~/.config/opencode/llmapi.key}" is also supported.

2.3 Gateway Caveats

• The gateway must be compatible with OpenAI Chat Completions (/v1/chat/completions)
• The keys of models must match the model field accepted by the gateway API
• If the endpoint uses /v1/responses, use @ai-sdk/openai as the npm package instead
• Model IDs are subject to the gateway’s documentation

3. Multi-Model Configuration

Declare all models under provider.<id>.models and divide the work between model and small_model:

{
  "provider": {
    "llmapi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "llmapi",
      "options": {
        "baseURL": "https://api.xxx.com/v1",
        "apiKey": "{env:LLMAPI_KEY}"
      },
      "models": {
        "glm-5.2": { "name": "GLM 5.2" },
        "deepseek-v4-pro": { "name": "DeepSeek V4 Pro" },
        "deepseek-v4-flash": { "name": "DeepSeek V4 Flash" }
      }
    }
  },
  "model": "llmapi/glm-5.2",
  "small_model": "llmapi/deepseek-v4-flash"
}

3.1 Switching Within a Session

1
2

/models      # 选择模型
/provider    # 切换 Provider

4. Usage Tips

4.1 Everyday Development

• Default to GLM 5.2 day to day, and switch to Pro in /models when coding gets hard
• Flash is configured as small_model; lightweight tasks use it automatically, so there is no need to switch manually

4.2 Troubleshooting Checklist

5. Complete Example

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "llmapi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "llmapi",
      "options": {
        "baseURL": "https://api.xxx.com/v1",
        "apiKey": "{env:LLMAPI_KEY}"
      },
      "models": {
        "glm-5.2": { "name": "GLM 5.2" },
        "deepseek-v4-pro": { "name": "DeepSeek V4 Pro" },
        "deepseek-v4-flash": { "name": "DeepSeek V4 Flash" }
      }
    }
  },
  "model": "llmapi/glm-5.2",
  "small_model": "llmapi/deepseek-v4-flash"
}

1
2
3

export LLMAPI_KEY=your-token
opencode
# TUI：/models 切换 GLM / Pro / Flash