# Claude Code

> Use Vikey in Claude Code through settings.json, including Claude model mapping, Vikey Auto and the model for background tasks.

Claude Code speaks the Anthropic format (`/v1/messages`). Vikey accepts that format, so you point Claude Code at Vikey and tell it which model ids to use.

Tested with Claude Code 2.1.323 on 13 November 2026.

## Recommended config

Write this to `~/.claude/settings.json` (Windows: `%USERPROFILE%\.claude\settings.json`). If the file already exists, merge the contents instead of overwriting it.

```json title="~/.claude/settings.json"
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.vikey.ai",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  },
  "modelOverrides": {
    "claude-opus-5-5": "anthropic/claude-opus-5.5",
    "claude-sonnet-5-5": "anthropic/claude-sonnet-5.5",
    "claude-haiku-5-5": "anthropic/haiku-5.5"
  }
}
```

Then run `claude` as usual. `/model sonnet`, `/model opus` and `/model haiku` now use the Claude models on Vikey.

### Why each line is there

| Line | Purpose |
| --- | --- |
| `ANTHROPIC_BASE_URL` | Sends every request to Vikey. Without `/v1`, because Claude Code adds `/v1/messages` itself. |
| `ANTHROPIC_AUTH_TOKEN` | Your Vikey API key, sent as `Authorization: Bearer`. It applies right away without a confirmation and takes precedence over a claude.ai login. |
| `CLAUDE_CODE_ATTRIBUTION_HEADER` | `0` removes a changing attribution block from the system prompt, so repeated prompt parts can be billed at the cache price. |
| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | `1` makes `/model` list the models from Vikey's `GET /v1/models`, so you can pick other models from the list. |
| `modelOverrides` | Claude Code's built-in model names (`claude-sonnet-5-5`) differ from Vikey model ids (`anthropic/claude-sonnet-5.5`). This mapping makes the `opus`, `sonnet` and `haiku` aliases and background tasks (session titles, summaries) use the right Vikey model, and Claude Code still knows what the model can do. |

**Keep the key out of your repository**

Keep this config in `~/.claude/settings.json` (all projects) or `.claude/settings.local.json` (one project, not committed). Never put the key in a project's `.claude/settings.json`, because that file is committed.

## Use Vikey Auto or non-Claude models

Claude Code can also run models other than Claude, such as GPT or DeepSeek, because Vikey translates the format. Add `model` to settings.json:

```json title="~/.claude/settings.json" ins={2}
{
  "model": "vikey/agent-coding",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.vikey.ai",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  },
  "modelOverrides": {
    "claude-opus-5-5": "anthropic/claude-opus-5.5",
    "claude-sonnet-5-5": "anthropic/claude-sonnet-5.5",
    "claude-haiku-5-5": "anthropic/haiku-5.5"
  }
}
```

Or for one session only: `claude --model vikey/agent-gpt`.

Common model ids:

| Model id | What it is |
| --- | --- |
| `vikey/agent-coding` | Vikey Auto with Claude models: Haiku 5.5, Sonnet 5.5, Opus 5.5 |
| `vikey/agent-gpt` | Vikey Auto with GPT models: GPT-6 Luna, GPT-5.6 Terra, GPT-6.1 Sol |
| `vikey/agent-mocin` | The cheapest Vikey Auto, DeepSeek V4.1 Flash models |
| `openai/gpt-6.1-sol`, `deepseek/deepseek-v4.1-flash` and others | One fixed model. Full list on the [pricing page](https://vikey.ai/en/pricing). |

With a model id Claude Code does not know, it prints `Claude Code doesn't recognize the model ...`. That is only a warning: in the version we tested, Claude Code assumes a 1 million token context window, which matches what Vikey lists for these models. For another limit, set `CLAUDE_CODE_MAX_CONTEXT_TOKENS`, for example `"CLAUDE_CODE_MAX_CONTEXT_TOKENS": "200000"` in the `env` block.

How Vikey Auto works and what it costs is explained in [Vikey Auto](/en/models/vikey-auto/).

## Try it without changing files

To try it in one terminal only:

**macOS / Linux**

  ```bash
  export ANTHROPIC_BASE_URL=https://api.vikey.ai
  export ANTHROPIC_AUTH_TOKEN=YOUR_API_KEY
  export ANTHROPIC_DEFAULT_HAIKU_MODEL=openai/gpt-6-luna
  claude --model vikey/agent-coding
  ```
**PowerShell**

  ```powershell
  $env:ANTHROPIC_BASE_URL = "https://api.vikey.ai"
  $env:ANTHROPIC_AUTH_TOKEN = "YOUR_API_KEY"
  $env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "openai/gpt-6-luna"
  claude --model vikey/agent-coding
  ```

`ANTHROPIC_DEFAULT_HAIKU_MODEL` replaces `modelOverrides` for background tasks. Without one of them, Claude Code sends its built-in model name for session titles and summaries, and those requests fail with `Model not found`.

## Test the connection

1. Test the key and base URL directly, without Claude Code:

    ```bash
    curl -sS https://api.vikey.ai/v1/messages \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "anthropic-version: 2023-06-01" \
      -H "content-type: application/json" \
      -d '{"model": "openai/gpt-6-luna", "max_tokens": 32, "messages": [{"role": "user", "content": "ping"}]}'
    ```

    A response with `"content"` means the key and base URL are right.

2. Run `claude`, send one message, then type `/status`. The **Anthropic base URL** line should show `https://api.vikey.ai`, and the **Auth token** line should name `ANTHROPIC_AUTH_TOKEN`.

## VS Code

The Claude Code extension for VS Code reads variables from VS Code's own settings. Open **Preferences: Open User Settings (JSON)** and add:

```json
{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://api.vikey.ai" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "YOUR_API_KEY" }
  ]
}
```

`modelOverrides` is still read from `~/.claude/settings.json`.

## Common problems

| What you see | Cause | Fix |
| --- | --- | --- |
| `Model 'claude-...' not found` | Claude Code sends its built-in model name | Add `modelOverrides` as above, or set `ANTHROPIC_DEFAULT_HAIKU_MODEL` |
| Asked to log in although curl works | The key is not read before the login screen | Put `ANTHROPIC_AUTH_TOKEN` in `~/.claude/settings.json` or export it in the shell, not in project settings |
| Warning about two login sources (`auth may not work as expected`) | The Vikey key and a claude.ai login are both active | Run `/logout` so only the Vikey key is used |
| `ANTHROPIC_API_KEY` ignored | This variable needs a one-time approval in interactive mode | Use `ANTHROPIC_AUTH_TOKEN`, or approve it in `/config` |
| `400` with `Extra inputs are not permitted` | A Claude Code beta feature the target model does not take | Add `"CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"` to the `env` block |
| `402 Insufficient balance` | No balance left | [Top up](/en/account/top-up/) and continue the session |

Source: https://docs.vikey.ai/en/agents/claude-code/