Agents & CLIs · Client configuration

Run OpenCode through one governed provider.

Give OpenCode one workload key and one approved model alias. Keep provider keys off developer machines, cap the workload, and change compatible backends behind the route.

Create a free workspace Try the no-card Test Lab

How the connection works

How OpenCode works with the gateway

Know which account pays

AIGHQ_API_KEY identifies the gateway workload. It does not reuse a Zen, Go, Anthropic, OpenAI, or other saved OpenCode credential; billing follows the provider account or prepaid managed route selected in AI Gateway HQ.

Put enforcement at the right config layer

OpenCode merges configuration files. Project and inline settings can override ordinary global or remote defaults. File-based managed settings and macOS MDM preferences load later and are the documented non-overridable choices for company enforcement.

Keep the protocol and tools compatible

The current adapter uses @ai-sdk/openai-compatible and /v1/chat/completions. Before enabling fallback, verify streamed events, tool calls, context limits, and error handling against every target behind the alias.

Runnable client path

Connect OpenCode while keeping provider secrets off the machine.

Add a dedicated OpenAI-compatible provider entry that reads its workload key from the environment.

Test the controls first

1
Create a OpenCode workload
Give each environment or agent its own key. Set the OpenCode budget, rate limit, route, and fallback first.
2
Keep the key out of configuration files
Store the OpenCode workload key in a keychain, CI secret, or secrets manager. The example contains no real credential.
3
Test both success and failure
Send a small OpenCode request and inspect its receipt. Test OpenCode's zero-balance stop and provider fallback too.

Personal subscription allowances are not imported.

OpenCode uses an AI Gateway HQ workload key. Requests from OpenCode charge the BYOK provider account or prepaid Bedrock balance selected by the route, not a personal subscription allowance.

OpenCode configuration

{
  "$schema": "https://opencode.ai/config.json",
  "model": "aighq/company-approved-fast",
  "enabled_providers": ["aighq"],
  "provider": {
    "aighq": {
      "name": "AI Gateway HQ",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://api.aigatewayhq.com/v1",
        "apiKey": "{env:AIGHQ_API_KEY}"
      },
      "models": {
        "company-approved-fast": {
          "name": "Company approved fast",
          "limit": {
            "context": 131072,
            "output": 16384
          }
        }
      }
    }
  }
}

Use the OpenCode production URL shown. For OpenCode, replace only the workload key and approved alias from the customer console.

This OpenCode setup was checked against the vendor's published interface. Before a broad OpenCode rollout, review the primary documentation because the vendor can change its interface.

Current shared controls

What every supported connection includes

Encrypted BYOK credentials that remain hidden after setup Stable model aliases and compatible route targets Organization and key budgets, rate limits, and concurrency limits Observe, Shadow, and Enforce modes with metadata-only evidence

Test the installed OpenCode version, resolved config, provider allowlist, model selection, streamed text, tool round trips, hard budget stop, and compatible fallback. For an enforceable company setting, deploy OpenCode's managed config or MDM preference rather than relying on a project file alone.

Client boundary

AIGHQ_BASE_URL=https://api.aigatewayhq.com/v1
AIGHQ_API_KEY=from-your-workspace
AIGHQ_MODEL=company-approved-fast

OpenCode sends Chat Completions traffic to the aighq provider only when the selected model begins with aighq/. AI Gateway HQ can change a compatible backend behind that stable alias, but it cannot govern calls that a user sends directly to another OpenCode provider.

Implemented boundary

Supported protocols

Add the aighq custom provider, read its workload key from AIGHQ_API_KEY, and select aighq/company-approved-fast. The example uses OpenCode's documented OpenAI-compatible package for /v1/chat/completions; Responses-based routes require a different client package and separate acceptance.

POST /v1/chat/completions OpenAI-compatible tool and stream events OpenCode provider/model aliases

Compatibility follows the provider's current published interface. Review the provider documentation before approving OpenCode for production.