# Claude Code Setup: Connect to ZRouter

> Connect Claude Code to ZRouter with an account API key for text-file coding and client-executed tools, then pick models and check what billing covers.

## What works

ZRouter account keys support client-executed tools and inline text tool results through `/v1/messages`, including streaming. Each model turn reserves credit and settles against reported token usage. Customer BYOK supports the same request shapes with its configured routing fees.

Start with a text-file coding task using a tool-capable Claude model. Provider-hosted search and code execution, media, server-side compaction, stored conversation references, and opaque reasoning replay remain unsupported. These limits also apply to BYOK. The setup below keeps the initial workflow inside this supported subset; it does not enable every Claude Code feature.

The gateway's automated integration tests cover a two-turn file-reading exchange through the Anthropic adapter, streaming and non-streaming responses, and fixed and provider-priced credit settlement. They use a local simulated provider. A live Claude Code session against a paid provider has not yet been certified.

## Connect your account

1. Create a dedicated account API key under **API Keys**.
2. Add credit, or save a supported Anthropic provider key under **Bring your own keys**.
3. Copy an enabled Claude model ID from **Models**, including its provider prefix.
4. Install Claude Code using [Anthropic's instructions](https://code.claude.com/docs/en/setup).

Set these variables in the terminal where you launch Claude Code. Replace the key and model placeholders. The base URL is the gateway root, without `/v1`.

```bash
export ANTHROPIC_BASE_URL="https://zrouter.si"
export ANTHROPIC_AUTH_TOKEN="YOUR_ZROUTER_ACCOUNT_KEY"
export ANTHROPIC_MODEL="ANTHROPIC_INSTANCE/CLAUDE_MODEL_ID"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="$ANTHROPIC_MODEL"
export ANTHROPIC_DEFAULT_SONNET_MODEL="$ANTHROPIC_MODEL"
export ANTHROPIC_DEFAULT_OPUS_MODEL="$ANTHROPIC_MODEL"
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=8192
export MAX_THINKING_TOKENS=0
export ENABLE_TOOL_SEARCH=false
claude --model "$ANTHROPIC_MODEL" --tools "Read,Glob,Grep,Bash,Edit,Write"
```

The output cap matches ZRouter's default. Use your workspace's limit if the operator changed it. Use a Claude model that permits thinking to be disabled for this initial workflow. The explicit tool list keeps provider-hosted web tools out of the session. Tool execution remains subject to Claude Code's normal permissions.

The helper-model variables keep auxiliary calls on an available model. Choose separate enabled models later if needed. Avoid setting `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` to different credentials. See [gateway configuration](https://code.claude.com/docs/en/llm-gateway-connect) and [environment variables](https://code.claude.com/docs/en/env-vars).

For customer BYOK, add this before launching the client:

```bash
export ANTHROPIC_CUSTOM_HEADERS="X-ZRouter-BYOK: true"
```

Your ZRouter account key still authenticates the request. The saved provider key stays on ZRouter. Without the BYOK header, requests use platform credit. Provider API charges are separate from Claude subscription usage.

## Verify the connection

First check model access without generating tokens:

```bash
curl "$ANTHROPIC_BASE_URL/v1/models" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```

Then launch Claude Code in a small test project and ask it to read one text file and explain it. Approve the read through the client's normal permission prompt. Check **Audit Logs** for the requests and **Billing & credits** for settled charges. This task consumes model tokens.

`POST /v1/messages/count_tokens` is available with account keys and does not deduct ZRouter credit. It uses the provider's counter when available, otherwise an estimate. Counting is advisory; request-size and output limits still apply.

## Editor extension

The Claude Code extension can use the same variables in user-level editor settings under `claudeCode.environmentVariables`. Keep credentials out of shared repository settings. An editor launched from the desktop may not inherit terminal variables. Restart the extension and select the configured model after changing its environment.

## Troubleshooting

- A `/v1/v1/messages` error means the base URL includes `/v1` twice.
- A model error requires an enabled Claude model, including any helper models.
- A hosted-tool rejection means the request includes a provider-executed tool. Start with the local tools listed above.
- An opaque-reasoning or media rejection requires a fresh text-only session with thinking disabled on a model that supports it.
- A large conversation can exceed the conservative input allowance, including tool definitions and results. Shorten the history or start a fresh session.
- A 402 response means the available balance cannot cover the reservation. The hold can exceed the final charge.

Use the supported text-file workflow and disable provider features outside account metering. Adding credit or switching to BYOK does not bypass these limits.

## Manage your account with MCP

The [account MCP server](/docs/mcp) lets an assistant inspect usage and manage routers, keys, and enabled limits. That connection is separate from the model-request configuration above.