Gate.AI Documentation

Create a Gate.AI API Key

1. Open gate.ai → Dashboard → API Keys, create and copy a key starting with sk-or-v1-…

2. Confirm your account has sufficient balance

Network connectivity check

Replace GATEAI_API_KEY with your key:

export GATEAI_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxx"

Anthropic-compatible endpoint (Claude Code):

curl -s -o /dev/null -w "%{http_code}" \
  -H "x-api-key: $GATEAI_API_KEY" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"anthropic/claude-sonnet-4.6","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}' \
  https://api.gate.ai/anthropic/v1/messages

• Returns 200: gateway is reachable; proceed with install and configuration

• Returns 401: invalid or expired key — check the dashboard

• Connection timeout: check local network or DNS; do not use https://api.gate.ai/v1

Install Claude Code CLI

macOS / Linux / WSL (recommended):

curl -fsSL https://claude.ai/install.sh | bash

Or with npm:

npm install -g @anthropic-ai/claude-code

If npm install fails

This is usually caused by registry.npmjs.org timeouts or instability — unrelated to the Gate.AI gateway. Try one of the following:

Option A: one-off install with a mirror (try first)

npm install -g @openai/codex --registry=https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

Option B: set mirror globally

# Use npmmirror (common in China)
npm config set registry https://registry.npmmirror.com

# Verify registry
npm config get registry

# Reinstall
npm install -g @openai/codex
npm install -g @anthropic-ai/claude-code

Option C: current shell session only

export NPM_CONFIG_REGISTRY=https://registry.npmmirror.com
npm install -g @openai/codex

Configure model

Replace all sk-or-v1-your-key placeholders with your real key. No need to repeat unless you change the key or model.

mkdir -p ~/.claude

cat > ~/.claude/settings.json <<'EOF'
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.gate.ai/anthropic",
    "ANTHROPIC_API_KEY": "sk-or-v1-your-key",
    "ANTHROPIC_MODEL": "anthropic/claude-sonnet-4.6"
  },
  "includeCoAuthoredBy": false
}
EOF

# Clear old Anthropic / proxy sessions to avoid auth conflicts
claude /logout 2>/dev/null || true
unset ANTHROPIC_AUTH_TOKEN

Store credentials only in settings.json. If ~/.zshrc still has ANTHROPIC_AUTH_TOKEN or a duplicate ANTHROPIC_API_KEY, comment or remove them.

Verify setup

In your project directory, start the CLI for AI-assisted coding in the terminal.

Run claude

claude

First check: run /status and confirm Base URL is https://api.gate.ai/anthropic and auth token is ANTHROPIC_API_KEY.

Advanced configuration

Auth conflict

If you see Auth conflict: Both a token (ANTHROPIC_AUTH_TOKEN) and an API key (ANTHROPIC_API_KEY) are set:

Alternative configuration

Shell environment variables (do not duplicate settings.json):

export ANTHROPIC_BASE_URL="https://api.gate.ai/anthropic"
export ANTHROPIC_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxx"
export ANTHROPIC_MODEL="anthropic/claude-sonnet-4.6"

Project-level settings (share structure; never commit real keys):

Model environment variables

Add to the env block in settings.json:

Full list: model catalog. If auto fails, use an explicit model ID.

Restore direct Anthropic (optional)

env -u ANTHROPIC_BASE_URL -u ANTHROPIC_API_KEY claude

Troubleshooting

Common Base URL mistakes

# ❌ Wrong (missing /anthropic prefix, 404)
https://api.gate.ai/v1
https://api.gate.ai/v1/chat/completions

# ❌ Wrong (do not use full API path in Claude config)
https://api.gate.ai/anthropic/v1/messages
https://api.gate.ai/anthropic/messages

# ✅ Correct
https://api.gate.ai/anthropic/v1
https://api.gate.ai/anthropic          # Claude Code CLI
https://api.gate.ai/anthropic/v1/messages  # curl key check (Anthropic)
https://api.gate.ai/openai/v1/responses    # curl key check (Codex)

• /openai/v1/chat/completions works, but Codex must use the Responses API. On 404 for /responses, check wire_api = "responses", not the URL.

• /openai/v1/models does not validate keys (invalid keys may still return 200). Use the curl endpoints above to verify keys.

Quick reference

Create a Gate.AI API Key

1. Open gate.ai → Dashboard → API Keys, create and copy a key starting with sk-or-v1-…

2. Confirm your account has sufficient balance

Network connectivity check

Replace GATEAI_API_KEY with your key:

export GATEAI_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxx"

OpenAI-compatible endpoint (Codex / standard API):

curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $GATEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-5.2","input":"hi","max_output_tokens":16}' \
  https://api.gate.ai/openai/v1/responses

• Returns 200: gateway is reachable; proceed with install and configuration

• Returns 401: invalid or expired key — check the dashboard

• Connection timeout: check local network or DNS; do not use https://api.gate.ai/v1

Install Codex CLI

npm install -g @openai/codex

Or

curl -fsSL https://chatgpt.com/codex/install.sh | sh

If you use Homebrew

brew install --cask codex

Verify: codex --version

If npm install fails

This is usually caused by registry.npmjs.org timeouts or instability — unrelated to the Gate.AI gateway. Try one of the following:

Option A: one-off install with a mirror (try first)

npm install -g @openai/codex --registry=https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

Option B: set mirror globally

# Use npmmirror (common in China)
npm config set registry https://registry.npmmirror.com

# Verify registry
npm config get registry

# Reinstall
npm install -g @openai/codex
npm install -g @anthropic-ai/claude-code

Option C: current shell session only

export NPM_CONFIG_REGISTRY=https://registry.npmmirror.com
npm install -g @openai/codex

Configure model

Replace all sk-or-v1-your-key placeholders with your real key. No need to repeat unless you change the key or model.

mkdir -p ~/.codex

cat > ~/.codex/config.toml <<'EOF'
model_provider = "gateai"
model = "openai/gpt-5.2"

[model_providers.gateai]
name = "Gate.AI"
base_url = "https://api.gate.ai/openai/v1"
env_key = "GATEAI_API_KEY"
wire_api = "responses"
requires_openai_auth = false
EOF

grep -q 'GATEAI_API_KEY=' ~/.zshrc 2>/dev/null || cat >> ~/.zshrc <<'EOF'

# Gate.AI for Codex CLI
export GATEAI_API_KEY="sk-or-v1-your-key"
EOF

source ~/.zshrc

Codex gateway settings must be in user-level ~/.codex/config.toml. Project-level .codex/config.toml cannot override these values.

Verify setup

In your project directory, start the CLI for AI-assisted coding in the terminal.

Run codex

codex

If you get a normal reply without 401 / 404, routing through Gate.AI succeeded.

Advanced configuration

Config reference

Alternative configuration

Built-in OpenAI provider (try if Option A auth fails)

model = "openai/gpt-5.2"
openai_base_url = "https://api.gate.ai/openai/v1"

Environment variable: export OPENAI_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxx"

Temporary CLI override

export GATEAI_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxx"
codex --config openai_base_url='"https://api.gate.ai/openai/v1"' --config model='"openai/gpt-5.2"'

Switch model

Edit model in ~/.codex/config.toml, or run: codex --model openai/gpt-5.2

Restore direct OpenAI (optional)

Remove Gate-related settings from ~/.codex/config.toml and unset GATEAI_API_KEY.

Troubleshooting

Common Base URL mistakes

# ❌ Wrong (missing /openai prefix, 404)
https://api.gate.ai/v1
https://api.gate.ai/v1/chat/completions

# ❌ Wrong (do not use full API path in Codex config)
https://api.gate.ai/openai/v1/messages
https://api.gate.ai/openai/messages

# ✅ Correct
https://api.gate.ai/openai/v1          # Codex CLI
https://api.gate.ai/anthropic/v1/messages  # curl key check (Anthropic)
https://api.gate.ai/openai/v1/responses    # curl key check (Codex)

• /openai/v1/chat/completions works, but Codex must use the Responses API. On 404 for /responses, check wire_api = "responses", not the URL.

• /openai/v1/models does not validate keys (invalid keys may still return 200). Use the curl endpoints above to verify keys.

Quick reference

Prerequisites

• Cursor is installed
• You have a Gate.AI API Key

Step 1: Open Cursor Settings

Open the top-right menu → Settings.

Step 2: Open Models Settings

In the left sidebar:

1. Find and open Models
2. Click View All Models
3. Scroll to the bottom and click Add Custom Model

Step 3: Add Configuration

Fill in the integration information:

Step 4: Save and Close Settings

After finishing the configuration, save it and close Settings.

Step 5: Use Gate.AI in Cursor

In Chat, Composer, Agent, and other conversation surfaces, search for or choose the model you just added from the model selector.

FAQ

If you already have Claude Code (Anthropic's terminal / IDE coding assistant) installed, follow these steps to connect Gate.AI.

1. Create a Gate.AI API key

1. Go to Dashboard → Settings → API Keys and create a key.
2. Copy the key that starts with sk-or-v1- and use it to replace the placeholders below.
3. For auto routing: go to Dashboard → Settings → Routing and enable Auto routing. When it is off, specify a model ID explicitly in each request.

2. Configure Anthropic Base URL and API key

Claude Code reads environment variables. We recommend following the official LLM gateway documentation and setting:

Option A: Current terminal session (temporary)

export ANTHROPIC_BASE_URL="https://api.gate.ai/anthropic"
export ANTHROPIC_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxx"
claude

Option B: Shell profile

Append the following to ~/.zshrc or ~/.bashrc:

export ANTHROPIC_BASE_URL="https://api.gate.ai/anthropic"
export ANTHROPIC_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxx"

After running source ~/.zshrc (or opening a new terminal), run claude.

Option C: Claude Code settings.json (recommended)

In user-level or project-level configuration, add an env block (see Claude Code settings for paths), for example in your project directory .claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.gate.ai/anthropic",
    "ANTHROPIC_API_KEY": "sk-or-v1-xxxxxxxxxxxxxxxx"
  }
}

Security note: Do not commit real keys to a public repository; use your OS secret store or CI secret injection, and keep local secrets in environment variables only.

Bypass the gateway and use Anthropic directly

To temporarily skip the gateway:

env -u ANTHROPIC_BASE_URL -u ANTHROPIC_API_KEY claude

(You must already have Anthropic official credentials or another default provider configured.)

3. Configure models (Gate.AI model IDs)

In Gate.AI docs, model IDs look like provider/model-name (for example anthropic/claude-sonnet-4.6). They are not identical to Claude Code built-in aliases such as sonnet. Pick one approach:

3.1 Default model via environment variable

export ANTHROPIC_MODEL="anthropic/claude-sonnet-4.6"

Or add the same key under env in settings.json.

3.2 Alias mapping

Map aliases to Gate.AI model IDs (Sonnet example):

export ANTHROPIC_DEFAULT_SONNET_MODEL="anthropic/claude-sonnet-4.6"
export ANTHROPIC_DEFAULT_OPUS_MODEL="anthropic/claude-opus-4.6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="anthropic/claude-haiku-4.5"

Use the Gate.AI docs — Models list as the source of truth for IDs.

3.3 Custom entry in /model

To pick a gateway-backed model in the UI, use Claude Code's custom model option (see the official Model configuration - ANTHROPIC_CUSTOM_MODEL_OPTION):

export ANTHROPIC_CUSTOM_MODEL_OPTION="anthropic/claude-sonnet-4.6"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Sonnet (Gate.AI)"

3.4 Auto-routing model auto

If auto routing is enabled in the dashboard, you can try setting ANTHROPIC_MODEL to auto (same meaning as auto on the OpenAI setup page). If you see errors, switch back to an explicit model ID such as anthropic/claude-sonnet-4.6.

4. Verify the setup

1. In a terminal with the environment configured, run:

claude

2. After the session starts, send a simple prompt, for example: In one sentence, introduce yourself.

3. If you get a normal reply with no auth or routing errors, requests are reaching Gate.AI and the selected model is responding.

5. FAQ

Prerequisites

• Claude Desktop is installed
• Gate.AI API Key

Step 1: Enable Developer Mode

1. Launch Claude Desktop. You do not need to sign in with an Anthropic account.
2. From the menu bar, choose Help → Troubleshooting → Enable Developer Mode.

After enabling it, the Developer menu appears in the menu bar.

Step 2: Open Third-Party Inference Settings

From the menu bar, choose Developer → Configure Third-Party Inference…

Step 3: Enter Gate.AI Credentials and Models

1. Choose Gateway and Static API key, then enter your Gate.AI credentials.
   After filling them in, click Test connection to test the connection.

2. Turn on Model discovery.
   After enabling it, you can click Test connection again.

3. Click Apply Changes to save.

Step 4: Restart and Launch

1. Fully quit Claude Desktop, including the app process, then reopen it.
2. On the launch page, choose Continue with Gateway. No Anthropic account is required.

Step 5: Verify

The connection is successful when the model picker shows available models.

FAQ

Authentication Errors

Routing and Model Errors

Request Parameter Errors

Quota and Rate Limit Errors

Billing and Balance Errors

Upstream Service Errors

Server Internal Errors

Common Quick Checks

Incorrect Base URL

# ❌ Incorrect
https://api.gate.ai/v1/chat/completions

# ✅ Correct
https://api.gate.ai/openai/v1/chat/completions  # OpenAI protocol
https://api.gate.ai/anthropic/v1/messages  # Anthropic protocol

Incompatible max_tokens Parameter

// ❌ Some models do not support this
{ "model": "gpt-4o", "max_tokens": 100 }

// ✅ Use max_completion_tokens
{ "model": "openai/gpt-5.5", "max_completion_tokens": 100 }

API Key Format

# ✅ Correct request headers
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx # OpenAI protocol
X-api-key: sk-xxxxxxxxxxxxxxxxxxxx # Anthropic protocol