AI Gateway HQ
Agents & CLIs · Client configuration

Operate OpenCode behind one governed boundary.

Add an OpenCode v2 custom provider that reads a workload key from the environment and uses the gateway's Chat Completions boundary.

Start in a test environment Read current API behavior
Runnable client path

Connect OpenCode without putting a provider secret on the machine.

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

Test the controls first
  1. 1
    Create a distinct workload

    Use one key for one environment or agent. Attach the hard dollar cap, rate boundary, approved route, and fallback before sending a request.

  2. 2
    Keep the key out of the configuration file

    Put AIGHQ_API_KEY in the local keychain, CI secret, or workload secret manager. The example contains no real credential.

  3. 3
    Prove both the allow and stop paths

    Run a small smoke test, inspect its metadata-only receipt, then exercise the zero-balance block and provider-health fallback.

Personal subscription allowances are not imported.

This setup uses an AI Gateway HQ workload credential. Requests are charged to the approved BYOK provider account or prepaid managed Bedrock balance selected by the route—not to a personal ChatGPT or Claude subscription allowance.

OpenCode configuration
{
  "$schema": "https://opencode.ai/config.json",
  "model": "aighq/company-approved-fast",
  "providers": {
    "aighq": {
      "name": "AI Gateway HQ",
      "env": ["AIGHQ_API_KEY"],
      "package": "@opencode-ai/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://api.aigatewayhq.com/v1",
        "apiKey": "{env:AIGHQ_API_KEY}"
      },
      "models": {
        "company-approved-fast": { "name": "Company approved fast" }
      }
    }
  }
}

Use the exact production origin shown. Replace only the workload key and organization-approved alias supplied inside the customer console.

Client configuration was checked against the vendor's current published interface. Review the primary documentation before a broad rollout because client capabilities change independently of the gateway.

Current shared controls

Status determines what can be configured.

Write-only, encrypted BYOK for implemented provider connections Stable model aliases and protocol-eligible route targets Organization and key budgets, RPM, TPM, and concurrency hard limits Observe, Shadow, Enforce, reason codes, and metadata-only evidence

Beta connections require customer validation against the exact model, payload, streaming mode, region, and provider account before production use.

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

Applications keep a stable gateway URL and model alias while an administrator changes eligible provider accounts and models.

Implemented boundary

Only documented protocols become eligible.

Add the dedicated aighq provider to opencode.json, read its workload key from AIGHQ_API_KEY, and select the organization-approved model alias.

POST /v1/chat/completions GET /v1/models connection test

Compatibility is bounded to the provider's current published interface. Review the provider documentation before approving a production model.

Client configurationCodex CLIClient configurationClaude Code