# Claude Code

> Connect Claude Code to Tokens through the Anthropic-compatible endpoint, map the opus, sonnet and haiku aliases to a Tokens model, and fix the usual gateway errors.

Claude Code is Anthropic's agentic coding CLI, which also runs inside VS Code and JetBrains. It speaks the Anthropic Messages API, so you point it at `https://tokens.bd` (no `/v1`) and it sends requests to [/v1/messages](/docs/messages).

:::warning[Non-Claude models are best effort]
Anthropic's gateway docs say it "doesn't support routing Claude Code to non-Claude models through any gateway". In practice it works when the model handles tool calls well, but that is per model and nobody guarantees it. If one struggles in long agent sessions, switch to another rather than fighting it.
:::

## Quick setup with the Tokens CLI

The [Tokens CLI](/docs/tokens-cli) signs you in through the browser, creates a key, lets you pick a model and writes Claude Code's settings for you. It needs Node 18 or newer.

:::code-tabs

```bash title="macOS / Linux"
curl -fsSL https://tokens.bd/cli/tokens.mjs -o tokens.mjs && node tokens.mjs setup --base-url https://tokens.bd --agents claude
```

```powershell title="Windows PowerShell"
iwr https://tokens.bd/cli/tokens.mjs -OutFile tokens.mjs; node tokens.mjs setup --base-url https://tokens.bd --agents claude
```

:::

It merges the base URL, key and model into the `env` block of `~/.claude/settings.json`, and points the `opus`, `sonnet` and `haiku` aliases and subagents at the same model. The old file is kept as `settings.json.tokens-backup-<timestamp>`. If the file has comments or a syntax error, the CLI leaves it alone and points you to [/dashboard/connect](/dashboard/connect) instead.

The CLI does not set `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` or the context window described below. Add them if a model needs them.

## Set ANTHROPIC_BASE_URL for Claude Code manually

Install Claude Code first if you haven't (`curl -fsSL https://claude.ai/install.sh | bash` on macOS/Linux, `irm https://claude.ai/install.ps1 | iex` in PowerShell, or `npm install -g @anthropic-ai/claude-code`). Then create a key at [/dashboard/keys](/dashboard/keys) (see [API keys](/docs/api-keys)).

### Option A: environment variables

Good for trying things out, or if you never want the key in a file.

:::code-tabs

```bash title="macOS / Linux"
export TOKENS_API_KEY="tok_live_your_key"
export ANTHROPIC_BASE_URL="https://tokens.bd"
export ANTHROPIC_AUTH_TOKEN="$TOKENS_API_KEY"
export ANTHROPIC_MODEL="deepseek/deepseek-v4.1-flash"
export ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek/deepseek-v4.1-flash"
export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek/deepseek-v4.1-flash"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek/deepseek-v4.1-flash"
export CLAUDE_CODE_SUBAGENT_MODEL="deepseek/deepseek-v4.1-flash"
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
```

```powershell title="Windows PowerShell"
$env:TOKENS_API_KEY = "tok_live_your_key"
$env:ANTHROPIC_BASE_URL = "https://tokens.bd"
$env:ANTHROPIC_AUTH_TOKEN = $env:TOKENS_API_KEY
$env:ANTHROPIC_MODEL = "deepseek/deepseek-v4.1-flash"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL = "deepseek/deepseek-v4.1-flash"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "deepseek/deepseek-v4.1-flash"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "deepseek/deepseek-v4.1-flash"
$env:CLAUDE_CODE_SUBAGENT_MODEL = "deepseek/deepseek-v4.1-flash"
$env:CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS = "1"
```

:::

`$env:` lasts for the current PowerShell window. Use `setx NAME "value"` for each variable to keep it in new windows.

### Option B: ~/.claude/settings.json

Values in the settings file's `env` block win over shell exports. On Windows the file is `%USERPROFILE%\.claude\settings.json`.

```json title="~/.claude/settings.json"
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://tokens.bd",
    "ANTHROPIC_AUTH_TOKEN": "tok_live_your_key",
    "ANTHROPIC_MODEL": "deepseek/deepseek-v4.1-flash",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek/deepseek-v4.1-flash",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek/deepseek-v4.1-flash",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek/deepseek-v4.1-flash",
    "CLAUDE_CODE_SUBAGENT_MODEL": "deepseek/deepseek-v4.1-flash",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "128000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}
```

:::warning[Keep the key out of project files]
Only put the key in your user-level `~/.claude/settings.json`, never in a repository's `.claude/settings.json`. To keep it out of files entirely, drop `ANTHROPIC_AUTH_TOKEN` from the JSON and export it in your shell profile as in Option A.
:::

`128000` is a placeholder. Set `CLAUDE_CODE_MAX_CONTEXT_TOKENS` to the real context window shown on the model's page in [/models](/models).

What the variables do:

| Variable                                    | Purpose                                                                                                                                 |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `ANTHROPIC_AUTH_TOKEN`                      | Sends `Authorization: Bearer`. `ANTHROPIC_API_KEY` also works (sends `x-api-key`) but asks for a one-time approval in interactive mode. |
| `ANTHROPIC_MODEL`                           | Model for the session.                                                                                                                  |
| `ANTHROPIC_DEFAULT_OPUS/SONNET/HAIKU_MODEL` | Back the `opus`, `sonnet` and `haiku` aliases. Haiku also runs background tasks.                                                        |
| `CLAUDE_CODE_SUBAGENT_MODEL`                | Model for subagents.                                                                                                                    |
| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`    | Strips most Claude-only beta fields from requests.                                                                                      |

### VS Code extension

Set the same variables in your VS Code user settings:

```json title="settings.json (VS Code)"
{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://tokens.bd" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "tok_live_your_key" },
    { "name": "ANTHROPIC_MODEL", "value": "deepseek/deepseek-v4.1-flash" }
  ]
}
```

Set them here even if they are also in `~/.claude/settings.json`, because the extension's login check doesn't read that file.

## Switch models

Change `ANTHROPIC_MODEL` and the four alias variables to another id and restart Claude Code. Keep them in sync, or the `opus` alias and background tasks keep running the old model. Copy exact ids from [/models](/models), from `node tokens.mjs models`, or from `GET /v1/models`. [Choosing a model](/docs/choosing-a-model) covers which models suit agent work.

The `/model` picker won't list Tokens models on its own. Gateway model discovery is off unless you set `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`, and it keeps only ids containing `claude` or `anthropic`. To add one extra entry to the picker, set `ANTHROPIC_CUSTOM_MODEL_OPTION` to a model id.

## Verify it works

Test the endpoint directly first (macOS, Linux, WSL or Git Bash):

```bash
curl -sS -w '\n%{http_code}\n' -X POST "https://tokens.bd/v1/messages" \
  -H "Authorization: Bearer $TOKENS_API_KEY" \
  -H "anthropic-version: 2023-06-01" -H "content-type: application/json" \
  -d '{"model": "deepseek/deepseek-v4.1-flash", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'
```

A `200` means the key and model are fine. Then run `claude`, type `/status`, and check that the base URL line shows `https://tokens.bd` and the auth token line names `ANTHROPIC_AUTH_TOKEN`. `claude doctor` validates your settings files. The request should also appear in Usage analytics in the dashboard.

## Troubleshooting

**404 on every request.** The base URL has an extra path after the host. Use `https://tokens.bd`. A base URL ending in `/v1` also works.

**401 `invalid_api_key` even though you exported a new key.** The `env` block in `~/.claude/settings.json` overrides your shell. Check which value `/status` reports.

**400 errors about `thinking`, effort or unknown fields.** For model ids it doesn't recognize, Claude Code sends adaptive thinking, effort and beta tool fields. `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` removes most of them, though not thinking or effort; Claude Code retries without those when the upstream rejects them. If a model still fails, try another one.

**The session never compacts, or hits "prompt too long".** Claude Code assumes 200K tokens of context for ids it doesn't recognize, and says so with a "doesn't recognize the model" warning at startup. Set `CLAUDE_CODE_MAX_CONTEXT_TOKENS` to the model's real window. `CLAUDE_CODE_AUTO_COMPACT_WINDOW` (minimum 100,000) and `CLAUDE_CODE_MAX_OUTPUT_TOKENS` give finer control.

**Unexpected model in your usage log.** Background tasks use `ANTHROPIC_DEFAULT_HAIKU_MODEL`, or the main model if it's unset.

**Features missing.** Remote Control and voice dictation are disabled while a gateway credential is set, and fast mode checks Anthropic's API directly, so it won't work through Tokens.

**403 `model_not_allowed_on_key` or `tier_permission_denied`, 402, or 429 `window_exhausted`.** These are account limits, not Claude Code problems. See [Troubleshooting](/docs/troubleshooting) and include the `x-tokens-request-id` header value if you open a ticket.

---
Page: https://tokens.bd/docs/claude-code
