Integrating AvalAI with Claude Code

Claude Code is Anthropic's powerful agentic coding CLI that lives in your terminal, reads your codebase, edits files, and runs commands on your behalf. By default it talks to Anthropic's own API, but Claude Code also honors a set of environment variables that let you point it at any Anthropic-compatible endpoint. That means you can route Claude Code through AvalAI and use your AvalAI API key to access Claude models—along with over 410 other advanced AI models available through AvalAI.

Because Claude Code is deeply agentic, it relies heavily on tool calling to read/write files and execute terminal commands. AvalAI natively supports Anthropic's Messages API (v1/messages)—the exact endpoint Claude Code uses—so Claude models work seamlessly with all of Claude Code's agentic capabilities. No proxy or translation layer is required.

💰 Special Offer

Take advantage of AvalAI's exclusive credit packages and receive up to 70% more credit or enjoy up to 40% discount on your purchases. These exclusive offers help you maximize your AI development budget!

Why Integrate AvalAI with Claude Code?

Connecting Claude Code to AvalAI brings powerful capabilities to your terminal:

• Use Your AvalAI Key: Run Claude Code with a single AvalAI API key instead of a separate Anthropic account
• Access to 410+ Models: Use Claude Opus 4.8, Claude 5 Sonnet, and Claude Haiku 4.5—but also open-source and third-party models such as GLM-5.2, Kimi K2.7 Code, Gemini 3.1 Pro, and GPT-5.5, all over the same Anthropic-compatible endpoint
• Full Agentic Coding: Generate code, refactor, debug, run commands, and edit files directly from the CLI
• Anthropic-Compatible API: AvalAI exposes an Anthropic-compatible endpoint, so Claude Code works with just a few environment variables
• Cost-Effectiveness: Benefit from AvalAI's competitive pricing, aligned with original provider rates
• Flexibility: Choose the best Claude model for each task—deep reasoning, fast coding, or cost-effective development

Obtaining Your AvalAI API Key (Step-by-Step)

Follow these steps to obtain your AvalAI API key:

1. Create an AvalAI Account: If you don't already have one, visit the AvalAI Dashboard and create an account.

2. Access the API Keys Page: Once logged in, navigate to the "API Keys" section in your dashboard.

3. Generate a New API Key: Click the button to "Generate new key" or "Create secret key."

4. Name Your Key (Optional): Give your API key a descriptive name like "Claude Code Development" to help organize and manage your keys.

5. Copy Your API Key: After generating the key, it will be displayed once. Important: Copy this key immediately and store it securely. You won't be able to see the full key again for security reasons.

Install Claude Code

If you haven't installed Claude Code yet, install the CLI first.

On macOS, Linux, or WSL, use the native installer:

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

On Windows, install Node.js 18+ first, then open PowerShell as Administrator and install Claude Code with npm:

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

You can also use the npm command above on macOS, Linux, or WSL if you prefer npm over the native installer.

Verify the installation:

claude --version

Configure Claude Code for AvalAI (Direct / Recommended)

Claude Code reads its provider configuration from environment variables. Because AvalAI natively serves Anthropic's Messages API (v1/messages), you can point Claude Code directly at AvalAI without any proxy or translation layer.

Set the following environment variables in your terminal:

macOS / Linux (bash or zsh):

export ANTHROPIC_BASE_URL="https://api.avalai.ir"
export ANTHROPIC_AUTH_TOKEN="your-avalai-api-key"
export ANTHROPIC_MODEL="claude-opus-4-8"
export ANTHROPIC_SMALL_FAST_MODEL="claude-haiku-4-5"

Here's what each variable does:

• ANTHROPIC_BASE_URL — Redirects Claude Code's requests to AvalAI's Anthropic-compatible endpoint (https://api.avalai.ir).
• ANTHROPIC_AUTH_TOKEN — Your AvalAI API key. Claude Code sends this as the bearer token for authentication.
• ANTHROPIC_MODEL — The primary (large) model Claude Code uses for its main reasoning and coding work.
• ANTHROPIC_SMALL_FAST_MODEL — A smaller, faster model Claude Code uses for lightweight background tasks (such as summaries and title generation). Using an efficient model here keeps costs down.

Security Tip

Prefer ANTHROPIC_AUTH_TOKEN (or ANTHROPIC_API_KEY) sourced from an environment variable rather than hard-coding your key anywhere. Never commit your key to version control.

Make the Settings Persistent

To avoid re-typing these variables every time you open a new terminal window, add them to your shell configuration profile.

1. Open your Zsh configuration file (the default shell on macOS):

nano ~/.zshrc

2.  Scroll to the bottom of the file and append the AvalAI configuration:

    ```bash
# AvalAI configuration for Claude Code
export ANTHROPIC_BASE_URL="https://api.avalai.ir"
export ANTHROPIC_AUTH_TOKEN="your-avalai-api-key"
export ANTHROPIC_MODEL="claude-opus-4-8"
export ANTHROPIC_SMALL_FAST_MODEL="claude-haiku-4-5"

3. Press Ctrl + O then Enter to save, and Ctrl + X to exit the nano editor.

4. Apply the changes immediately to your current terminal session:

source ~/.zshrc

> **Tip:** If you use bash, add the same lines to `~/.bashrc` or `~/.bash_profile` and run `source ~/.bashrc` instead.

**Windows (PowerShell):**

Open a new PowerShell window and set the variables for the current session:

```powershell
$env:ANTHROPIC_BASE_URL = "https://api.avalai.ir"
$env:ANTHROPIC_AUTH_TOKEN = "your-avalai-api-key"
$env:ANTHROPIC_API_KEY = $env:ANTHROPIC_AUTH_TOKEN
$env:ANTHROPIC_MODEL = "claude-opus-4-8"
$env:ANTHROPIC_SMALL_FAST_MODEL = "claude-haiku-4-5"

Windows first-run note

On a fresh Windows installation, Claude Code may still open the Anthropic browser login if only ANTHROPIC_AUTH_TOKEN is set. Setting ANTHROPIC_API_KEY to the same AvalAI key lets Claude Code detect a custom API key during initialization. When Claude Code asks whether to use the detected custom API key, choose Yes.

To make these permanent on Windows, use PowerShell's user environment variable API (then close and reopen PowerShell):

[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.avalai.ir", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "your-avalai-api-key", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "your-avalai-api-key", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_MODEL", "claude-opus-4-8", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_SMALL_FAST_MODEL", "claude-haiku-4-5", "User")

After reopening PowerShell, verify that Windows can see the values:

echo $env:ANTHROPIC_BASE_URL
echo $env:ANTHROPIC_AUTH_TOKEN
echo $env:ANTHROPIC_API_KEY

Alternative: Project-Level Settings File

Instead of environment variables, you can store the same configuration in Claude Code's settings file. Create or edit ~/.claude/settings.json (user-level) or .claude/settings.json (project-level):

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.avalai.ir",

    "ANTHROPIC_AUTH_TOKEN": "your-avalai-api-key",
    "ANTHROPIC_API_KEY": "your-avalai-api-key",
    "ANTHROPIC_MODEL": "claude-opus-4-8",
    "ANTHROPIC_SMALL_FAST_MODEL": "claude-haiku-4-5"
  }
}

Important

If you commit project-level .claude/settings.json to version control, do not include your real API key in it. Keep secrets in environment variables and reserve the settings file for non-sensitive values like ANTHROPIC_BASE_URL and model names.

Run Claude Code

With your environment variables set, launch Claude Code from your project directory:

cd /path/to/your/project
claude

On Windows PowerShell, use Windows paths instead:

cd C:\path\to\your\project
claude

Claude Code will start an interactive session using the AvalAI endpoint and the Claude model you configured. Try a simple prompt to verify the connection:

Tell me about this project

If you see a normal response, your integration is working! 🎉

Verify the Active Configuration

Inside a Claude Code session, you can inspect and change your active setup:

• /status — Shows which API endpoint and models are serving your current session.
• /model — Lists or switches the model used for the current session.

One-Off Model Overrides

You can override the model for a single run without editing your shell profile:

# Launch with a specific model for this session only
claude --model claude-sonnet-5

# Or set it inline for a single invocation
ANTHROPIC_MODEL="claude-opus-4-8" claude

Do I Need a Translation Proxy?

No. Because AvalAI natively serves Anthropic's Messages API (v1/messages)—the same endpoint Claude Code talks to—you can use the direct method above with no proxy, LiteLLM, or community adapter. This is the simplest and recommended setup for Claude models.

A translation proxy would only be relevant if you wanted to drive Claude Code with a model that only speaks the OpenAI Chat Completions format and does not support the Anthropic Messages API. Since AvalAI already exposes Claude models over the native Anthropic endpoint, you can skip that complexity entirely.

Recommendation

Stick with the direct method. Set ANTHROPIC_BASE_URL to https://api.avalai.ir and your ANTHROPIC_AUTH_TOKEN to your AvalAI key—that's all Claude Code needs.

Using Models from Other Providers

Claude Code isn't limited to Claude models. Because most models on AvalAI are also served over the native Messages API (v1/messages), you can point ANTHROPIC_MODEL at open-source and third-party models too—no proxy required. Simply change the model value:

# Open-source models
export ANTHROPIC_MODEL="glm-5.2"
export ANTHROPIC_MODEL="kimi-k2.7-code"

# Google Gemini
export ANTHROPIC_MODEL="gemini-3.1-pro-preview"

# OpenAI
export ANTHROPIC_MODEL="gpt-5.5"

Compatibility Note

Most models on AvalAI work over the v1/messages endpoint, but full compatibility across every single model isn't guaranteed—some may not fully support the Anthropic Messages format (especially its tool-calling structure). If a specific model doesn't behave properly with Claude Code, please contact AvalAI support and we'll do our best to make it work over the Messages endpoint.

Discover the latest models

Browse the AvalAI news feed to see the newest models added to the platform and their identifiers.

Choosing the Right Model

AvalAI offers access to 410+ models. Here are some recommendations for coding tasks with Claude Code:

For Complex Code Generation & Reasoning

• Claude Opus 4.8 (claude-opus-4-8) - Best for complex reasoning and large codebases
• Claude 5 Sonnet (claude-sonnet-5) - Great balance of speed and quality
• GPT-5.5 (gpt-5.5) - Excellent for advanced problem-solving

For Fast, Efficient Agentic Coding

• Claude Haiku 4.5 (claude-haiku-4-5) - Fast and efficient, ideal for the ANTHROPIC_SMALL_FAST_MODEL role
• Claude 5 Sonnet (claude-sonnet-5) - Strong everyday coding performance
• Kimi K2.7 Code (kimi-k2.7-code) - Strong open-source coding model for agentic workflows

For Cost-Effective Development

• GLM-5.2 (glm-5.2) - Capable open-source model at lower cost
• Gemini 3.1 Pro (gemini-3.1-pro-preview) - Fast, multimodal, and economical

Tip

Pair a powerful primary model (ANTHROPIC_MODEL) with an efficient small model (ANTHROPIC_SMALL_FAST_MODEL) to balance quality and cost—Claude Code routes lightweight background tasks to the small model automatically.

Tips and Best Practices

• Secure Storage: Treat your AvalAI API key like a password. Source it from an environment variable and never commit it to version control.
• Small Fast Model: Set ANTHROPIC_SMALL_FAST_MODEL to an economical model like claude-haiku-4-5 so background tasks stay cheap.
• Git Checkpoints: Claude Code can modify your codebase. Create Git checkpoints before and after each task so you can easily revert changes if needed.
• CLAUDE.md: Add a CLAUDE.md file to your repository to give Claude Code consistent project guidance (build commands, conventions, and expectations).
• Rate Limits: Be aware of AvalAI's rate limits. Most coding tasks stay well within limits, but be mindful with large agentic runs.
• Cost Monitoring: Track your usage through the AvalAI dashboard to monitor costs and optimize model selection.

Troubleshooting

• Invalid API Key / Authentication Error:

  • Confirm the ANTHROPIC_AUTH_TOKEN environment variable is set: run echo $ANTHROPIC_AUTH_TOKEN (macOS/Linux) or echo $env:ANTHROPIC_AUTH_TOKEN (Windows PowerShell).
  • On Windows first run, also confirm ANTHROPIC_API_KEY is set with echo $env:ANTHROPIC_API_KEY; this prevents Claude Code from falling back to the Anthropic browser login flow.
  • Restart your terminal (or run source ~/.zshrc) after setting the variable so Claude Code can read it.
  • Verify the key is still active in your AvalAI dashboard.

• Requests Still Going to Anthropic:

  • Ensure ANTHROPIC_BASE_URL is set to https://api.avalai.ir (no trailing /v1 for the direct Anthropic-compatible endpoint).
  • Run /status inside Claude Code to confirm the active endpoint.
  • If you previously logged in with an Anthropic account, log out so Claude Code uses the environment variables instead.

• Connection Issues:

  • Verify your internet connection.
  • Check that no firewall or proxy is blocking https://api.avalai.ir.

• Model Not Found Error:

  • Confirm the model identifier is correct (check the AvalAI models overview).
  • Try a common model like claude-opus-4-8 or claude-sonnet-5.

• Tool Calls / Agentic Actions Failing:

  • Make sure the model you selected supports tool use. Claude models on AvalAI do.
  • Claude models on AvalAI support tool use over the native Messages API, so no special translation is needed.

• Rate Limit Errors:

  • Review your rate limits for your tier.
  • Wait a moment before retrying, or consider upgrading your tier for higher limits.

Conclusion

Integrating AvalAI with Claude Code is quick and typically requires no proxy: set a handful of environment variables—ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, and your preferred models—and Claude Code will run entirely on your AvalAI API key.

This lets you enjoy Claude's deep reasoning and full agentic coding directly in your terminal, backed by AvalAI's competitive pricing and access to 410+ models.

Related Resources

• AvalAI API Reference: Introduction
• AvalAI Messages API (Anthropic-compatible)
• AvalAI Models Overview
• Latest Models & News
• Rate Limits Guide
• Integrating AvalAI with OpenAI Codex
• Integrating AvalAI with VSCode Extensions
• Model Selection Guide
• Claude Code Official Documentation