Client setup

General rules §

For any client, change the same two settings:

• Endpoint URL — Set it to http://127.0.0.1:3001. Whether to include /v1 depends on the client; see the examples below.
• Key — Use the AccessKey created in the management UI, not the upstream provider's key.

Keep the client's native authentication method; the gateway accepts Authorization: Bearer, x-api-key, x-goog-api-key, and Gemini's key query parameter.

Let the management UI generate the configuration §

The management UI can generate connection settings for each client. Select an AccessKey and target client, then copy the generated configuration.

View full size

Supports Claude Code, Codex, Gemini CLI, Cherry Studio, Cline, NextChat, Open WebUI, CC Switch, New API, and curl. The generated configuration states which protocol the client needs, so tick that one and you cannot go wrong.

OpenAI SDK§

The official SDK requires only two changes:

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:3001/v1",    # Change this line 
    api_key= "Your AccessKey" ,           # Change this line 
)

resp = client.chat.completions.create(
    model= "Your model name" ,
    messages=[{"role": "user", "content":  "Hello" }],
)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://127.0.0.1:3001/v1",
  apiKey:  "Your AccessKey" ,
});

Environment variables work too: set OPENAI_BASE_URL and OPENAI_API_KEY without changing the code.

Anthropic SDK§

from anthropic import Anthropic

client = Anthropic(
    base_url="http://127.0.0.1:3001",    # Note: do not include /v1 
    api_key= "Your AccessKey" ,
)

Anthropic clients use /v1/messages. The SDK appends that path, so set base_url to the server root.

Claude Code§

Use environment variables to point to the gateway:

export ANTHROPIC_BASE_URL="http://127.0.0.1:3001"
export ANTHROPIC_AUTH_TOKEN= "Your AccessKey" 
export ANTHROPIC_MODEL="YOUR_MODEL"
export ANTHROPIC_CUSTOM_MODEL_OPTION="$ANTHROPIC_MODEL"
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"

claude

Replace YOUR_MODEL with a model ID available to this AccessKey, then start or restart Claude Code in the same shell. This model is selected at startup and added as a custom option in /model. Automatic discovery additionally lists only model IDs containing claude or anthropic, case-insensitively.

Add the variables to your shell profile to make them persistent. Enable the Anthropic Messages protocol on this AccessKey.

Codex CLI§

Selecting Codex on the console home page generates the configuration file and environment variables. Model discovery returns only models allowed by the current AccessKey with a Responses generation route. Here is a text-only setup example.

model = "YOUR_MODEL"
model_provider = "gpt-load"

[model_providers.gpt-load]
name = "OpenAI"
base_url = "http://127.0.0.1:3001/v1"
model_catalog_url = "http://127.0.0.1:3001/v1/models"
env_key = "GPT_LOAD_API_KEY"
wire_api = "responses"
supports_websockets = true

[features]
api_key_model_discovery = true

export GPT_LOAD_API_KEY="YOUR_ACCESS_KEY"

Replace YOUR_MODEL with an enabled model, merge the configuration, and restart the client. Model-discovery settings require client support; use the configuration generated by the current console.

Choose and order the models shown in Codex from the Models page. See Codex model catalog.

codex --enable reasoning_effort_override

This switch depends on the client version. Displaying reasoning levels in the catalog does not establish support for updates within a session.

Codex live voice: client configuration, direct media, and relay deployment →

Gemini CLI§

export GOOGLE_GEMINI_BASE_URL="http://127.0.0.1:3001"
export GEMINI_API_KEY= "Your AccessKey" 

Gemini clients use /v1beta/models/…. Enable the Gemini protocol on the AccessKey.

Desktop clients §

GUI clients such as Cherry Studio, NextChat, Open WebUI, and Cline usually expose Custom API Address and API Key fields. Configure them as follows:

• API Address: http://127.0.0.1:3001/v1
• API Key: your AccessKey
• Model: enter a model exposed by the Group. Some clients can fetch the list automatically with Get Models.

For screenshot steps specific to a client, using the management UI's one-click generation is faster—it will give the exact fields corresponding to that client.

For CC Switch balance queries, use the generic template with an AccessKey and set the Base URL to the gateway root or /v1. The result is an estimated USD balance from the AccessKey's total cost limit, not the upstream account balance. Periodic limits are excluded; without a total limit, total and balance are both 0.

When unable to connect §

Troubleshoot in this order; the first two steps identify most problems:

1. Use curl first to verify the gateway itself — This separates gateway behavior from client configuration problems:

curl http://127.0.0.1:3001/v1/chat/completions \
  -H  "Authorization: Bearer Your AccessKey"  \
  -H "Content-Type: application/json" \
  -d '{ "model":"Your model name","messages":[{"role":"user","content":"hi"}]}'

2. curl works but the client does not — Usually the endpoint has an extra or missing /v1, or the protocol is not enabled on the AccessKey.
3. Prompt indicates the model does not exist — Confirm that the model is exposed in the Group's Models tab.
4. Request sent but failed — Use Request Logs in Monitoring and troubleshooting for the exact error; Route Check shows candidate Groups and the number of available credentials.