Use OpenCode with CometAPI

Use this guide to run OpenCode with CometAPI. The configuration exposes four API formats through separate custom providers. This configuration was tested with OpenCode 1.18.16. Official references:

Replace each your-model-id value with a model ID from the CometAPI Models page. Choose a model that accepts the API format of the surrounding provider entry.

Prerequisites

Node.js and npm, or another installation method from the OpenCode guide
A CometAPI account with an active API key from the dashboard
One or more model IDs from the CometAPI Models page

Understand the API formats

Each provider ID selects one SDK adapter and one API format.

Provider ID	OpenCode adapter	Base URL	API format
`cometapi-chat`	`@ai-sdk/openai-compatible`	`https://api.cometapi.com/v1`	Chat Completions
`cometapi-responses`	`@ai-sdk/openai`	`https://api.cometapi.com/v1`	Responses
`cometapi-messages`	`@ai-sdk/anthropic`	`https://api.cometapi.com/v1`	Anthropic Messages
`cometapi-gemini`	`@ai-sdk/google`	`https://api.cometapi.com/v1beta`	Gemini generateContent

This guide verifies the Gemini streaming operation used during a normal OpenCode agent turn. The Google adapter appends :streamGenerateContent?alt=sse to the model path. Do not add /chat/completions, /responses, /messages, or a Gemini model path to baseURL. Each adapter appends its required operation path.

Understand runtime permissions

OpenCode runs with the permissions of the process that launches it. Start OpenCode in the intended project directory and keep a rollback path such as git. Use a container or sandbox when you need stronger filesystem, process, network, or API key boundaries.

Configure OpenCode

Install OpenCode

Install OpenCode with the official npm package:

npm install -g opencode-ai

Confirm that the CLI is available:

opencode --version

See the OpenCode installation guide for Homebrew, Windows, Docker, and other installation methods.

Set your CometAPI API key

Store your CometAPI API key in the COMETAPI_KEY environment variable.

macOS / Linux / WSL
Windows PowerShell

Read the API key without displaying it in the terminal:

read -rsp "CometAPI API key: " COMETAPI_KEY
printf '\n'
export COMETAPI_KEY

Read the API key into the current PowerShell session:

$secureKey = Read-Host "CometAPI API key" -AsSecureString
$env:COMETAPI_KEY = [System.Net.NetworkCredential]::new(
  "",
  $secureKey
).Password

Set the variable in every shell session that launches OpenCode. Do not commit API keys to version control.

Choose a configuration location

Use one of these supported locations:

Global configuration: ~/.config/opencode/opencode.json
Project configuration: opencode.json in the project root

OpenCode merges configuration files. A project configuration overrides conflicting values from the global configuration.Use the global file when you want the providers in every project. Use the project file when a repository needs its own model entries.

Add the CometAPI providers

Create the selected configuration file. If the file already contains a provider object, merge these four entries into that object:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "cometapi-chat": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "CometAPI Chat Completions",
      "options": {
        "baseURL": "https://api.cometapi.com/v1",
        "apiKey": "{env:COMETAPI_KEY}"
      },
      "models": {
        "your-model-id": {
          "name": "CometAPI Chat model"
        }
      }
    },
    "cometapi-responses": {
      "npm": "@ai-sdk/openai",
      "name": "CometAPI Responses",
      "options": {
        "baseURL": "https://api.cometapi.com/v1",
        "apiKey": "{env:COMETAPI_KEY}"
      },
      "models": {
        "your-model-id": {
          "name": "CometAPI Responses model"
        }
      }
    },
    "cometapi-messages": {
      "npm": "@ai-sdk/anthropic",
      "name": "CometAPI Anthropic Messages",
      "options": {
        "baseURL": "https://api.cometapi.com/v1",
        "apiKey": "{env:COMETAPI_KEY}"
      },
      "models": {
        "your-model-id": {
          "name": "CometAPI Messages model"
        }
      }
    },
    "cometapi-gemini": {
      "npm": "@ai-sdk/google",
      "name": "CometAPI Gemini",
      "options": {
        "baseURL": "https://api.cometapi.com/v1beta",
        "apiKey": "{env:COMETAPI_KEY}"
      },
      "models": {
        "your-model-id": {
          "name": "CometAPI Gemini model"
        }
      }
    }
  }
}

Replace each your-model-id key independently. The four entries can use different model IDs.The configuration does not set a top-level model. This lets you choose the required API format and model through /models.

Do not use /connect for this configuration. The apiKey fields read COMETAPI_KEY from the environment. An unset variable resolves to an empty value instead of a stored /connect API key.

Select and verify each provider

Start OpenCode in the project that you want it to access:

opencode

Run /models, then select a provider/model entry. In the four verification runs for this guide, each model turn used the selected entry’s matching API format. No cross-format request fan-out or automatic API format negotiation was observed.To verify Chat Completions from the command line, run:

opencode run \
  --model cometapi-chat/your-model-id \
  "Reply exactly with: COMETAPI_CHAT_OK"

To verify Responses from the command line, run:

opencode run \
  --model cometapi-responses/your-model-id \
  "Reply exactly with: COMETAPI_RESPONSES_OK"

To verify Anthropic Messages from the command line, run:

opencode run \
  --model cometapi-messages/your-model-id \
  "Reply exactly with: COMETAPI_MESSAGES_OK"

To verify Gemini generateContent from the command line, run:

opencode run \
  --model cometapi-gemini/your-model-id \
  "Reply exactly with: COMETAPI_GEMINI_OK"

Troubleshooting

OpenCode does not show a CometAPI model

Confirm that the configuration is valid JSON. Each custom entry must be inside the top-level provider object, and each model ID must be inside the matching models object. Restart OpenCode, then open /models again.

OpenCode reports an API key or authentication error

Confirm that COMETAPI_KEY is set in the shell that launches OpenCode. An unset {env:COMETAPI_KEY} reference becomes an empty value. Open a new shell after changing a shell profile.

A model ID is unavailable

Check the CometAPI Models page, then replace the model ID inside the selected provider entry. Confirm that the model accepts that provider’s API format.

Requests use an incorrect path

Keep baseURL at /v1 for Chat Completions, Responses, and Messages. Use /v1beta for Gemini. Do not include an operation path in baseURL.

One provider works but another provider fails

Use a model ID that accepts the selected provider’s API format. Do not assume that one model ID accepts all four formats.

The project configuration changes a global provider

OpenCode merges global and project configuration. Rename the project provider ID or remove its conflicting values when you want the global provider entry to remain unchanged.

OpenCode has more access than expected

OpenCode uses the permissions of the process that launched it. Run OpenCode in a container or sandbox when you need stronger access boundaries.

Overview

AI coding agents

AI agents

AI chat clients

Translation and language

Automation platforms

Observability and evaluation

AI frameworks

Prerequisites

Understand the API formats

Understand runtime permissions

Configure OpenCode

Troubleshooting

​Prerequisites

​Understand the API formats

​Understand runtime permissions

​Configure OpenCode

​Troubleshooting

​Related resources

Prerequisites

Understand the API formats

Understand runtime permissions

Configure OpenCode

Troubleshooting

Related resources