Integrating with OpenCode

OpenCode is an open-source, SST-built alternative to Claude Code. It can talk to xmAI via either the OpenAI Chat Completions protocol or the Anthropic Messages protocol — pick whichever fits the model you want to use.

Prerequisites

• Registered at XmAI Console with credits available (free tier included)
• Created an API Key on the API Keys page (format sk-xxx...)
• Installed OpenCode (brew install sst/tap/opencode or see upstream docs)

Configuration

OpenCode reads a global config at ~/.config/opencode/opencode.json and (optionally) a per-project opencode.json at the repository root. Both files share the same schema; per-project wins.

Version note

OpenCode is evolving quickly. The provider block structure below follows the current schema at opencode.ai/docs/providers. If your installed OpenCode version uses a different key, defer to upstream docs.

Option A — OpenAI-compatible mode (recommended for GPT / Gemini / mixed models)

Use the @ai-sdk/openai-compatible adapter and point it at https://api.xmai.sg/v1:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "xmai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "xmAI",
      "options": {
        "baseURL": "https://api.xmai.sg/v1",
        "apiKey": "{env:XMAI_API_KEY}"
      },
      "models": {
        "gpt-4o": { "name": "GPT-4o" },
        "gpt-4o-mini": { "name": "GPT-4o mini" },
        "claude-sonnet-4-6": { "name": "Claude Sonnet 4.6 (via xmAI)" },
        "gemini-2.5-pro": { "name": "Gemini 2.5 Pro" }
      }
    }
  },
  "model": "xmai/gpt-4o"
}

Export the key in your shell profile so {env:XMAI_API_KEY} resolves:

macOS / Linux / Git Bash

export XMAI_API_KEY="sk-your-xmai-key"

Windows PowerShell

$env:XMAI_API_KEY = "sk-your-xmai-key"

Windows CMD

set XMAI_API_KEY=sk-your-xmai-key
:: Current session only. For persistence: setx XMAI_API_KEY "sk-your-xmai-key"

Then run opencode — the status bar should show xmAI / gpt-4o. On Windows, prefer setx (or the System Properties → Environment Variables panel) so the key survives shell restarts.

Option B — Anthropic-compatible mode (for Claude models with native /v1/messages)

Use the @ai-sdk/anthropic adapter and point it at the xmAI root (no /v1 suffix — Anthropic SDK appends it):

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "xmai-anthropic": {
      "npm": "@ai-sdk/anthropic",
      "name": "xmAI (Anthropic mode)",
      "options": {
        "baseURL": "https://api.xmai.sg",
        "apiKey": "{env:XMAI_API_KEY}"
      },
      "models": {
        "claude-opus-4-6": { "name": "Claude Opus 4.6 (1M beta)" },
        "claude-sonnet-4-6": { "name": "Claude Sonnet 4.6 (1M beta)" },
        "claude-3-5-sonnet-20241022": { "name": "Claude Sonnet 3.5 v2" },
        "claude-3-5-haiku-20241022": { "name": "Claude Haiku 3.5" }
      }
    }
  },
  "model": "xmai-anthropic/claude-sonnet-4-6"
}

Both options can coexist — define both providers and switch via /model in the OpenCode UI.

Model Routing

xmAI's model catalog spans multiple vendors through a single key. Below is a snapshot; always cross-check with /v1/models at runtime (or the Models page).

xmAI model ID	Vendor	Typical use
gpt-4o	OpenAI	General-purpose, multimodal
gpt-4o-mini	OpenAI	Fast / low-cost
claude-opus-4-6	Anthropic	Highest quality (1M beta)
claude-sonnet-4-6	Anthropic	Balanced quality/cost (1M beta)
claude-3-5-sonnet-20241022	Anthropic	Legacy Sonnet 3.5 v2
claude-3-5-haiku-20241022	Anthropic	Fast / low-cost
gemini-2.5-pro	Google	Long-context reasoning
gemini-2.5-flash	Google	Fast / low-cost

/v1/models is authoritative. If a model ID returns 404 model not found, check the model list first.

Verifying the connection

Launch OpenCode and send any message, or run /help. Then:

1. Log into the Console → Request Logs to confirm the request landed
2. Or watch the Today's Usage card on the Dashboard for credit consumption

A new row in the log = you're connected.

Troubleshooting

Connection / TLS errors

System proxy interference: If http_proxy / https_proxy are set, they may intercept xmAI traffic. Exclude the xmAI domain:

export NO_PROXY="api.xmai.sg"

Self-signed certificates: In corporate networks with custom CA chains, import them:

export NODE_EXTRA_CA_CERTS=/path/to/your-ca-chain.pem

Auth failures (401 / 403)

• Check key status / expiry on the API Keys page
• Verify XMAI_API_KEY is actually exported in the shell where opencode runs (OpenCode forks a fresh shell — .zshrc / .bashrc must be sourced automatically, or set it in the OS env panel on Windows)
• For Anthropic mode: confirm baseURL has no trailing /v1 — the SDK appends /v1/messages itself

Model not found (404)

• /v1/models is the source of truth. Remove any model IDs not listed there.
• Anthropic-style prefixes like anthropic/claude-3-5-sonnet are not valid — use the plain claude-3-5-sonnet-20241022 ID instead.

Insufficient balance (402)

xmAI deducts per-token in real time. When your balance runs out, requests return 402 or insufficient_balance. Top up on the wallet page, or enable auto-topup.

Switching back to the original upstream

Set "model" to a model served by the default OpenAI / Anthropic providers, or delete the xmai / xmai-anthropic blocks from opencode.json.

Related

• Chat Completions API — underlying OpenAI-compatible API
• Messages API — underlying Anthropic-compatible API
• Models — available models and pricing
• Error Codes — error handling guide
• Claude Code — Anthropic-native alternative
• OpenAI-Compatible Tools — generic guide for other tools