Integrating with Claude Code

xmAI is natively compatible with the Anthropic Messages API (/v1/messages) and can serve as the custom upstream for the Claude Code CLI. Two environment variables are all that's needed — no changes to Claude Code itself.

Prerequisites

Registered at XmAI Console with credits available (free tier included)
Created an API Key on the API Keys page (format sk-xxx...)
Installed the Claude Code CLI

Configuration

Claude Code recognizes custom upstreams via two environment variables:

Variable	Value	Notes
`ANTHROPIC_BASE_URL`	`https://api.xmai.sg`	xmAI gateway root (no `/v1` suffix — Claude Code appends it automatically)
`ANTHROPIC_AUTH_TOKEN`	`sk-<your-xmai-key>`	Sends `Authorization: Bearer <token>`, matching xmAI auth

Why not ANTHROPIC_API_KEY?

ANTHROPIC_API_KEY sends the x-api-key header (Anthropic's official style). xmAI uses OpenAI-style Bearer auth, so you must use ANTHROPIC_AUTH_TOKEN. Use one or the other — never both.

Option A — Persist in settings.json (recommended)

Add to ~/.claude/settings.json (global) or .claude/settings.json at project root:

json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.xmai.sg",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-xmai-key"
  }
}

Restart Claude Code to pick up the change.

Option B — Current session only

macOS / Linux / Git BashWindows PowerShellWindows CMD

bash

export ANTHROPIC_BASE_URL="https://api.xmai.sg"
export ANTHROPIC_AUTH_TOKEN="sk-your-xmai-key"
claude

powershell

$env:ANTHROPIC_BASE_URL = "https://api.xmai.sg"
$env:ANTHROPIC_AUTH_TOKEN = "sk-your-xmai-key"
claude

cmd

set ANTHROPIC_BASE_URL=https://api.xmai.sg
set ANTHROPIC_AUTH_TOKEN=sk-your-xmai-key
claude

Option C — Persist in shell profile

Add the two export lines from Option B to ~/.bashrc / ~/.zshrc (Linux/macOS), or set them as user environment variables on Windows.

Model Routing (required)

Claude Code's default model IDs do not fully match the IDs xmAI currently ships. Without explicit mapping via environment variables you'll get 404 model not found.

Claude models available on xmAI

xmAI model ID	Official model	Context	Max output tokens
`claude-opus-4-6`	Claude Opus 4.6	1M (beta)	32K
`claude-sonnet-4-6`	Claude Sonnet 4.6	1M (beta)	64K
`claude-3-5-sonnet-20241022`	Claude Sonnet 3.5 (v2)	200K	8K
`claude-3-5-haiku-20241022`	Claude Haiku 3.5	200K	8K

Authoritative list comes from /v1/models at runtime.
1M context note: Opus 4.6 / Sonnet 4.6's 1M context is an Anthropic beta and requires the header anthropic-beta: context-1m-2025-08-07. Without it the effective window is 200K. Claude Code doesn't currently inject this header — use a proxy or wait for native support if you actually need 1M.
Claude 4.7 isn't on xmAI yet; request access via Admin → Models if needed.

Recommended mapping for Claude Code

In ~/.claude/settings.json, pin model slots explicitly:

json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.xmai.sg",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-xmai-key",
    "ANTHROPIC_MODEL": "claude-opus-4-6",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-3-5-haiku-20241022"
  }
}

Variable	Purpose	Recommended
`ANTHROPIC_MODEL`	Session main model (code generation, multi-step reasoning)	`claude-opus-4-6` or `claude-sonnet-4-6`
`ANTHROPIC_DEFAULT_OPUS_MODEL`	Model ID that the `opus` alias resolves to	`claude-opus-4-6`
`ANTHROPIC_DEFAULT_SONNET_MODEL`	Model ID that the `sonnet` alias resolves to	`claude-sonnet-4-6`
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	Model ID that the `haiku` alias resolves to	`claude-3-5-haiku-20241022`

ANTHROPIC_SMALL_FAST_MODEL is deprecated

Older Claude Code versions used ANTHROPIC_SMALL_FAST_MODEL for the fast / low-cost slot. This variable has been replaced by ANTHROPIC_DEFAULT_HAIKU_MODEL. If you have both set, the new variable takes precedence.

Setting only BASE_URL + AUTH_TOKEN without MODEL will cause Claude Code to request claude-opus-4-7 or similar IDs that xmAI hasn't onboarded, resulting in 404.

See Models for the full list of IDs and pricing.

Verifying the connection

Fire a test message in Claude Code:

/doctor

Or just ask Claude anything. Then:

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

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

Advanced Configuration

Disable non-essential traffic

When using a third-party proxy like xmAI, Claude Code still sends telemetry, auto-update checks, error reports, and feedback surveys to Anthropic's servers. To disable all of these:

json

{
  "env": {
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

Add this to ~/.claude/settings.json alongside the other variables. Claude Code functionality is unaffected — only background traffic is suppressed.

Routing to non-Claude models

The ANTHROPIC_DEFAULT_*_MODEL variables accept any model ID your upstream supports, not just Claude models. If xmAI has onboarded models from other providers (e.g., Gemini, DeepSeek), you can route Claude Code's model tiers to them:

json

{
  "env": {
    "ANTHROPIC_MODEL": "claude-opus-4-6",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "gemini-2.5-pro",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "gemini-2.5-pro",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "gemini-2.5-flash"
  }
}

Feature compatibility

Claude Code's advanced features (extended thinking, adaptive reasoning, effort levels) rely on matching model IDs against known Anthropic patterns. When routing to non-Claude models, these features may be unavailable or silently ignored.

Check Models for all available model IDs on xmAI.

Troubleshooting

Connection / TLS errors

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

bash

export NO_PROXY="api.xmai.sg"

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

bash

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

Switching back to Anthropic

Unset ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN (or remove them from settings.json's env field). Claude Code falls back to its default Anthropic authentication.

Auth failures (401 / 403)

Check key status / expiry on the API Keys page
Verify you're using ANTHROPIC_AUTH_TOKEN, not ANTHROPIC_API_KEY
Confirm ANTHROPIC_BASE_URL has no trailing /v1

Insufficient balance

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.

Messages API Reference — Anthropic-compatible API docs
Chat Completions API — OpenAI-compatible API docs
Models — available models and pricing
Error Codes — error handling guide
FAQ
OpenCode — open-source Claude Code alternative
OpenAI Codex CLI — OpenAI's terminal coding agent
Gemini CLI — limitations + workarounds
OpenAI-Compatible Tools — generic OpenAI-compatible guide

Integrating with Claude Code ​

Prerequisites ​

Configuration ​

Option A — Persist in settings.json (recommended) ​

Option B — Current session only ​

Option C — Persist in shell profile ​

Model Routing (required) ​

Claude models available on xmAI ​

Recommended mapping for Claude Code ​

Verifying the connection ​

Advanced Configuration ​

Disable non-essential traffic ​

Routing to non-Claude models ​

Troubleshooting ​

Connection / TLS errors ​

Switching back to Anthropic ​

Auth failures (401 / 403) ​

Insufficient balance ​

Related ​

Integrating with Claude Code

Prerequisites

Configuration

Option A — Persist in settings.json (recommended)

Option B — Current session only

Option C — Persist in shell profile

Model Routing (required)

Claude models available on xmAI

Recommended mapping for Claude Code

Verifying the connection

Advanced Configuration

Disable non-essential traffic

Routing to non-Claude models

Troubleshooting

Connection / TLS errors

Switching back to Anthropic

Auth failures (401 / 403)

Insufficient balance

Related