Connect Teapot Router to your client

Get these three things ready

Treat your API key as a password. Never put it in a chat, screenshot, document, or public repository. Paste it only into a client you trust.

Codex CLI: make your first request

Open a separate bash, zsh, or Windows PowerShell terminal and use the generated Codex CLI command through Teapot Router. First confirm an enabled Responses channel, model, and account balance.

1. Sign in to a real Teapot Router account and prepare a usable API key. Demo keys cannot call a model.
2. Ask an administrator for a small test credit, either through an enabled redemption code or an admin quota adjustment. Confirm the increased balance under Billing.
3. Ask the administrator to enable a real Responses-compatible upstream channel and model. A balance alone cannot make an unavailable channel work.
4. Choose your operating system, an existing key, a model, and either persistent or one-session mode. Copy the generated command and paste it into a matching bash/zsh or Windows PowerShell terminal, not Codex Settings. The preview hides the key; the copied command includes it.
5. Ask the new Codex CLI to reply OK, then check the request under Usage. Exit this test CLI when done; your original session remains available.

(
  printf 'OpenAI Base URL (ends in /v1): '
  IFS= read -r RELAY_BASE
  printf 'Responses model ID: '
  IFS= read -r RELAY_MODEL
  printf 'Teapot Router API Key: '
  IFS= read -r -s RELAY_KEY_FOR_CODEX
  printf '\n'
  export RELAY_KEY_FOR_CODEX
  codex -m "$RELAY_MODEL" \
    -c 'model_provider="relay"' \
    -c "model_providers.relay={name=\"Teapot Router\",base_url=\"$RELAY_BASE\",env_key=\"RELAY_KEY_FOR_CODEX\",wire_api=\"responses\",requires_openai_auth=false}"
)

One-session mode only affects the current terminal. Persistent mode creates a separate Teapot Router profile and leaves your existing Codex settings untouched; Windows stores the key with the current user's DPAPI and macOS/Linux use the system keychain or a separate profile. The complete copied command may remain in your clipboard and shell history; use a private terminal and clear them after testing. For 401, check the key; for model/channel errors, check NEW-API channels.

Claude Code

Use this path for Claude Code in a terminal. The commands below affect only your current terminal session and do not overwrite your existing client settings.

1. If Claude Code is not installed, install it using its official instructions and confirm that the claude command starts.
2. In the Teapot Router workspace, open Configure your client → Claude Code. Copy the gateway root URL, reveal your key, and copy a Claude model ID from Before you start on this page.
3. Open a terminal. Replace <TEAPOT_API_BASE_URL> and <CLAUDE_MODEL_ID> below with your actual values. Run the commands, then paste the key when prompted and press Enter. The key will not appear as you type.
4. Send a short message such as “Reply with OK” in Claude Code. Then check the corresponding request under Usage in Teapot Router.

macOS / Linux (bash, zsh)

export ANTHROPIC_BASE_URL="<TEAPOT_API_BASE_URL>"
printf 'Teapot Router API Key: '
read -rs ANTHROPIC_AUTH_TOKEN
printf '
'
export ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_MODEL="<CLAUDE_MODEL_ID>"
export ANTHROPIC_DEFAULT_SONNET_MODEL="$ANTHROPIC_MODEL"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="$ANTHROPIC_MODEL"
export ANTHROPIC_DEFAULT_OPUS_MODEL="$ANTHROPIC_MODEL"
claude

Windows PowerShell

$env:ANTHROPIC_BASE_URL = "<TEAPOT_API_BASE_URL>"
$secret = Read-Host "Teapot Router API Key" -AsSecureString
$env:ANTHROPIC_AUTH_TOKEN = [System.Net.NetworkCredential]::new("", $secret).Password
$env:ANTHROPIC_MODEL = "<CLAUDE_MODEL_ID>"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = $env:ANTHROPIC_MODEL
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = $env:ANTHROPIC_MODEL
$env:ANTHROPIC_DEFAULT_OPUS_MODEL = $env:ANTHROPIC_MODEL
claude

These variables last only for this terminal session. For a persistent setup, use a configuration method supported by Claude Code and back up any existing settings before editing them.

OpenAI-compatible client

Use this path for a chat app with a custom OpenAI provider or an application using the OpenAI SDK. Menu names vary, but the three values are the same.

1. Open your client's provider or API settings. Choose OpenAI compatible, Custom OpenAI, or a custom endpoint.
2. Set Base URL to the address under OpenAI-compatible in Teapot Router's setup dialog; it must end in /v1. Set API Key to the real key you revealed.
3. Enter the full model ID enabled for your key. Save, send a short message, and verify the request under Usage in Teapot Router.

# First run: python3 -m pip install openai
from getpass import getpass
from openai import OpenAI

base_url = input("Teapot Router Base URL (ends in /v1): ").strip()
model = input("Model ID: ").strip()
client = OpenAI(base_url=base_url, api_key=getpass("Teapot Router API Key: "))
result = client.chat.completions.create(
    model=model,
    messages=[{"role": "user", "content": "Reply with OK."}],
)
print(result.choices[0].message.content)

Verify the connection

Copying values or clicking “I've configured my client” does not prove a client request succeeded. Verify one real request.

1. Your client shows a model reply, not just a “settings saved” message.
2. Under Usage in Teapot Router, find the request with the matching time, model, and key.
3. Click Check request on the workspace overview. If this was the account's first request, the third step updates. Refresh and check the account if it does not.

Troubleshooting

Still stuck? Share your client name, the error text, and the time with support. Never send your full API key.