Set Up Claude Code With a Custom Base URL

1. Gather your endpoint and API key

Claude Code can connect through a custom API endpoint instead of its default service. The setup requires an installed CLI, a compatible endpoint, and an API key accepted by that endpoint. This walkthrough covers Windows PowerShell, macOS Terminal, and Linux shells.

For pay-as-you-go access, we recommend RelayVano, an AI model relay used by developers across many countries. Sign up for RelayVano, add credit as needed, and create an API key in your account. Its API base is https://api.relayvano.com.

Keep the key private. Do not paste it into a repository, shared document, screenshot, or support ticket. Replace YOUR_RELAYVANO_KEY in the commands below with your actual key.

2. Install Claude Code for your operating system

Use the official native installer. These commands download and execute an installation script, so confirm the address before running them.

• Windows: open PowerShell and run: irm https://claude.ai/install.ps1 | iex
• macOS: open Terminal and run: curl -fsSL https://claude.ai/install.sh | bash
• Linux: open your terminal and run: curl -fsSL https://claude.ai/install.sh | bash

On native Windows, install Git for Windows if Git Bash is not already available; Claude Code needs it. If you prefer Windows Subsystem for Linux, follow the Linux instructions inside WSL, including the environment configuration.

Close and reopen your terminal, then run: claude --version. If the command is not found, follow the installer's PATH instructions before continuing.

3. Set the custom base URL and token

Start with temporary environment variables. They apply to the current terminal session and programs launched from it, making them convenient for testing without changing your permanent configuration.

On Windows PowerShell, run:

$env:ANTHROPIC_BASE_URL = "https://api.relayvano.com"; $env:ANTHROPIC_AUTH_TOKEN = "YOUR_RELAYVANO_KEY"

On macOS or Linux, run:

export ANTHROPIC_BASE_URL="https://api.relayvano.com"; export ANTHROPIC_AUTH_TOKEN="YOUR_RELAYVANO_KEY"

Use the base URL exactly as shown. Do not append /v1/messages or assume that an OpenAI-style /v1 suffix belongs here. Claude Code needs an Anthropic-compatible endpoint; OpenAI compatibility alone is not sufficient.

If ANTHROPIC_API_KEY is already set for another service, remove it from this test session to avoid competing credentials. In PowerShell, run: Remove-Item Env:ANTHROPIC_API_KEY -ErrorAction SilentlyContinue. On macOS or Linux, run: unset ANTHROPIC_API_KEY.

4. Launch Claude Code and check the connection

Navigate to a small project directory, then run: claude. Complete any first-run prompts and review the directory trust request before accepting it. Launch from the same terminal where you configured the variables.

Send a simple prompt: Reply with a short greeting without reading or changing files. A successful response confirms that the request can reach a working model through your configured route. Check your relay usage dashboard for the corresponding request, allowing for reporting delays.

If the default model is unavailable, use Claude Code's /model command or its --model option with an exact model identifier supplied by your relay. Do not assume a dashboard display name is also a valid API identifier.

5. Save the configuration across restarts

After the test succeeds, open your user-level Claude Code settings file: ~/.claude/settings.json on macOS or Linux, or .claude\settings.json inside your Windows user profile. Create the directory and file if necessary.

For a new settings file, use this JSON:

{"env":{"ANTHROPIC_BASE_URL":"https://api.relayvano.com","ANTHROPIC_AUTH_TOKEN":"YOUR_RELAYVANO_KEY"}}

If settings already exist, merge these entries into the existing env object rather than replacing the file. This stores the token in plaintext: restrict access to the file, and never commit it. Restart Claude Code after editing.

6. Troubleshoot before changing more settings

• Authentication error: verify the key, account balance, and endpoint. Remove stale credentials from the launching shell.
• Model unavailable: check the relay's current model identifiers and account access.
• 404 response: check for an extra path suffix and confirm Anthropic API compatibility.
• Connection failure: check DNS, firewall rules, VPN settings, and any corporate proxy.
• Wrong endpoint still used: inspect shell variables, user settings, and project settings for conflicting values.

Change one setting at a time and repeat the greeting test. Once it works reliably, move on to normal coding tasks.