Claude Code

This tutorial walks you through using the Kimchi Inference API with Claude Code, Anthropic's agentic coding tool. You'll route Claude Code through Kimchi's Anthropic-compatible endpoint and pin Kimchi-hosted models into the /model picker, alongside the built-in Anthropic entries, so you can switch between them at any time.

One Kimchi API key covers it all: Kimchi-hosted models, Claude models your organization exposes through connected providers, and Claude models on your own subscription login.

Overview

By the end of this tutorial, you'll be able to:

• Point Claude Code at Kimchi as a gateway
• Authenticate requests with your Kimchi API key sent as an X-API-Key header
• Use Kimchi-hosted models for agentic tasks in addition to Anthropic
• Switch between Kimchi and Anthropic models on demand using the /model picker
• With a Claude Pro, Max, or Teams plan: meter subscription traffic through the gateway for usage tracking and cost visibility

Prerequisites

1. A Kimchi API key - Go to Kimchi → API Keys and click + Create key. Copy the key and store it securely. See API Keys and Service Keys for the difference between the two key types.
2. Node.js 18 or higher - Check your version with node --version
3. Claude Code v2.1.242 or later - the modelPicker setting requires it. Install or update Claude Code:

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

claude --version

Configure Claude Code

Two settings connect Claude Code to Kimchi: ANTHROPIC_BASE_URL routes traffic to the Anthropic-compatible endpoint, and ANTHROPIC_CUSTOM_HEADERS attaches your Kimchi API key to every request as an X-API-Key header, which is how the gateway authenticates and attributes your usage.

Store them in ~/.claude/settings.json, Claude Code's persistent configuration file: that applies them to every project and to GUI-launched apps like the VS Code and JetBrains extensions, and keeps your key out of shell history. For a single-session setup instead, see Alternative: environment variables.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm.kimchi.dev/anthropic",
    "ANTHROPIC_CUSTOM_HEADERS": "X-API-Key: YOUR_KIMCHI_API_KEY",
    "ANTHROPIC_API_KEY": ""
  },
  "model": "glm-5.3[1m]",
  "modelPicker": {
    "options": [
      {
        "model": "glm-5.3[1m]",
        "label": "GLM 5.3 (Kimchi)"
      },
      {
        "model": "glm-5.3-flash[1m]",
        "label": "GLM 5.3 Flash (Kimchi)"
      },
      {
        "model": "kimi-k3",
        "label": "Kimi K3 (Kimchi)"
      }
    ],
    "replaceBuiltInOptions": false
  }
}

cd ~/your-project

claude

> Explain what this project does in one paragraph

Alternative: environment variables

For a single shell session, set the variables directly instead of editing settings.json:

export ANTHROPIC_BASE_URL="https://llm.kimchi.dev/anthropic"
export ANTHROPIC_CUSTOM_HEADERS="X-API-Key: YOUR_KIMCHI_API_KEY"

claude

The header value must be exactly X-API-Key: followed by a space and your key. The exports last until you close the shell.

Switching models

Run /model in a session and pick an entry, or edit the model key in settings.json to change the default for new sessions. Common choices:

To pin a default model without editing the file, export ANTHROPIC_MODEL (for example export ANTHROPIC_MODEL="glm-5.3-flash[1m]") - when set, it outranks the saved model key for new sessions.

Troubleshooting

401 Authorization Required, or "Not logged in - Please run /login"

Claude Code can't get a request authenticated and reports it as a login failure. Check, in order:

1. The header name is exactly X-API-Key, followed by a colon, a space, and your key:

   Bash

   # Correct
   ANTHROPIC_CUSTOM_HEADERS="X-API-Key: YOUR_KIMCHI_API_KEY"
   
   # Wrong - the gateway does not recognize these header names
   ANTHROPIC_CUSTOM_HEADERS="X-Kimchi-Key: YOUR_KIMCHI_API_KEY"
   ANTHROPIC_CUSTOM_HEADERS="ApiKey: YOUR_KIMCHI_API_KEY"

2. ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY are not set anywhere in your settings files or shell: Claude Code sends the first non-empty one as the request credential, which overrides the header setup.

3. The key itself is valid. If it was rotated or revoked, create a fresh one from the API Keys page.

4. If Kimchi-hosted models work but Claude models fail, the request reaches Anthropic without a credential it accepts: keep your subscription login active (run /login in Claude Code), or have your organization connect Anthropic as an external provider.

Requests fail with login prompts but no 401

Check that ANTHROPIC_BASE_URL is set to exactly https://llm.kimchi.dev/anthropic in the same shell or settings.json you're launching from. Missing or misspelled, Claude Code falls back to Anthropic's own endpoint: with a saved login everything keeps working but your traffic is unmetered by Kimchi, and without one you get repeated login prompts.

echo $ANTHROPIC_BASE_URL

Spend doesn't show in the console

In the Kimchi console, open the Analytics dashboard, set the time range to 24h, and filter by the API key you configured. If requests are missing, confirm Claude Code is running with the environment active (echo $ANTHROPIC_BASE_URL), and remember that the dashboard counts the requests the tool makes on your behalf, which can exceed what the tool itself reports. See Dashboard token usage.

Next steps