Connect OpenCode#

Connect OpenCode to OptScale AI so agent chats use models available through your OptScale AI organization.

In Chat, copy Base URL, API key, and Model name from Get connection values from Chat before configuring OpenCode.

For shared model naming rules and limitations, see External Tools overview.

Prerequisites#

Ensure the following prerequisites are met before configuring OpenCode:

• An organization exists and at least one Active provider is configured.
• Allowed providers are assigned to the user connecting OpenCode to OptScale AI.
• The OptScale AI deployment is accessible over HTTPS with a valid TLS certificate.
• For agent workflows that use tools, select a model that supports tool execution.

Configure OpenCode#

1. Open File → Settings in OpenCode.

   

2. Go to Server → Providers, scroll to Custom provider, and click + Connect.

   

3. Enter the Provider ID and Display name. The Provider ID can contain only lowercase letters, numbers, hyphens (-), and underscores (_). For example, use optscale-ai as the Provider ID and OptScale AI as the Display name.

   

4. Configure Base URL:

   • In OptScale AI Chat, open Connect this model to external tools → OPENAI-COMPATIBLE and copy Base URL.

     

   • In OpenCode, paste the value into Base URL.

     

5. Configure API key:

   • In OptScale AI Chat, open Connect this model to external tools → OPENAI-COMPATIBLE and copy API key.

     

   • In OpenCode, paste the value into API key.

     

6. Configure the model in the Models section:

   • In OptScale AI Chat, open Connect this model to external tools → OPENAI-COMPATIBLE and copy Model name.

     

   • In OpenCode, paste the value into the model-id field.

     

   • Enter a descriptive Display Name for the model, for example, OpenCode via OptScale AI.

     

7. Click Submit to save the provider configuration.

The configured model is now available in OpenCode under the custom provider.

Verify the OpenCode connection#

Open an OpenCode chat, select a configured model under the custom provider, and send the following prompt:

Reply with exactly: OptScale AI connection works.

The expected response is:

OptScale AI connection works.

In the Admin Console, open Analytics → Traces and confirm that a row appears for the selected Provider and Model. Requester is the user for whom the connection was configured.

See also#

• Get connection values from Chat — Shared Base URL, API key, and model values.
• External Tools — Overview and shared limitations.
• Connect Cursor — Point Cursor IDE at the gateway.
• Analytics → Traces — Verify requests after connecting.