Configuring OpenCode with Expedient AI Gateway

Configuring OpenCode with AI CTRL for VS Code

This guide is provided as-is and is not officially supported by Expedient. We aim to offer useful guidance, but make no guarantees about functionality, accuracy, or compatibility with your implementation. No support SLAs or warranties apply to the materials, scripts, or procedures described here.

OpenCode is a command-line coding assistant that runs inside Visual Studio Code. Because the AI CTRL gateway is OpenAI-compatible, you can point OpenCode at your own gateway rather than at a third-party AI service, so your code and prompts stay within your AI CTRL environment.

This guide covers the full setup: gathering your credentials, installing the CLI, configuring the provider, and connecting VS Code.

Before you start

Programmatic use is billed separately. Front-end chat in AI CTRL falls under fair use. Anything running through the API, including OpenCode, is metered and billed against your organization's consumption. Check with your administrator before running heavy workloads through it.

Step 1 · Gather your AI CTRL details

You need three things: your gateway URL, an API key, and the exact names of the models you want to use.

Your gateway URL

Note the address you use for AI CTRL, for example https://chat.yourcompany.com. You'll append /api/v1 to it in the configuration file.

Your API key

1. Sign in to AI CTRL
2. Click your profile picture, then Settings
3. Open the Account tab
4. Click Show next to API keys
5. Click Create new secret key
6. Copy the key and store it somewhere secure

Treat this key like a password. It grants access to your AI CTRL account, and the configuration file stores it in plain text on your machine. Don't commit opencode.json to a repository.

Your model names

OpenCode needs the exact model identifier, not the display name.

1. Click your profile picture, then Admin Panel
2. Go to Settings → Models
3. Open each model you want to use and copy the exact name shown beneath the display name

Finding model names requires admin access. If you're not an administrator, ask yours for the identifiers of the models you're licensed for.

Step 2 · Install the OpenCode CLI

macOS and Linux

1. Open your terminal.

2. Run the installation script:

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

   Or, if you prefer npm: npm install -g opencode-ai

3. Apply the PATH changes so the command works in your current session:

   source ~/.zshrc
   

4. Confirm it installed:

   opencode --version
   

   The terminal should return a version number.

Windows

1. Open PowerShell. Run as Administrator if you're using npm or Chocolatey; a standard user session is fine for Scoop.

2. Install the CLI globally:

   npm install -g opencode-ai
   

   Or use choco install opencode for Chocolatey, or scoop install opencode for Scoop.

3. Apply the PATH changes. Either close and reopen PowerShell, or run:

   $env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
   

4. Confirm it installed:

   opencode --version
   

Step 3 · Configure the provider

Open the configuration file

It will be empty the first time you open it.

• macOS and Linux — ~/.opencode/opencode.json, or ~/.config/opencode/opencode.json depending on your version
• Windows — press Windows + R, enter %USERPROFILE%\.opencode\opencode.json, and press Enter

Decide how much the assistant can do on its own

Two configurations below. The difference is whether OpenCode asks before changing files or running commands.

Ask first is the recommended starting point. The assistant proposes an edit or a command and waits for you to approve it. Slower, and you see everything before it happens.

Full access lets the assistant edit files and run commands without asking. Faster once you trust it, but it can change things you didn't expect. Don't use this in a repository you can't easily roll back.

Apply the configuration

Replace the entire contents of opencode.json with one of the blocks below, then make these three edits:

• Replace the baseURL with your own gateway URL, keeping /api/v1 on the end
• Replace your-api-key-here with the key from Step 1
• Replace the entries under models with the model identifiers you copied

Ask first (recommended):

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openwebui": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "AI CTRL",
      "options": {
        "baseURL": "https://chat.yourcompany.com/api/v1",
        "apiKey": "your-api-key-here"
      },
      "models": {
        "gemini/gemini-3.1-pro-preview": {
          "name": "Google Gemini 3.1 Pro (Preview)"
        },
        "gpt-5.4": {
          "name": "OpenAI GPT 5.4"
        },
        "claude-sonnet-4-6": {
          "name": "Anthropic Claude Sonnet 4.6"
        },
        "gpt-5.3-codex": {
          "name": "OpenAI GPT 5.3 Codex"
        }
      }
    }
  },
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Full access:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openwebui": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "AI CTRL",
      "options": {
        "baseURL": "https://chat.yourcompany.com/api/v1",
        "apiKey": "your-api-key-here"
      },
      "models": {
        "gemini/gemini-3.1-pro-preview": {
          "name": "Google Gemini 3.1 Pro (Preview)"
        },
        "gpt-5.4": {
          "name": "OpenAI GPT 5.4"
        },
        "claude-sonnet-4-6": {
          "name": "Anthropic Claude Sonnet 4.6"
        }
      }
    }
  }
}

Save and close the file.

Step 4 · Connect VS Code

1. Start the CLI. In your terminal, run:

   opencode
   

2. Install the extension. In VS Code, open Extensions (Ctrl+Shift+X on Windows, Cmd+Shift+X on macOS), search for OpenCode, and install the official extension.

   

3. Open the panel. Click the OpenCode icon in the VS Code sidebar. The panel opens to the right of your code.

   A file needs to be open for the icon to appear.

4. Choose a model. In the OpenCode panel, type /models and press Enter, then select the model you want.

That's the setup complete. You can now use the OpenCode panel for explanations, refactoring, and code generation, powered by your own AI CTRL gateway.

Related articles

• Settings, Memory & Your Data
• Available Models
• AI CTRL Ratecard