> ## Documentation Index
> Fetch the complete documentation index at: https://kiosapi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Claude Code CLI to Use KiosAPI as Backend

> Set up Anthropic's Claude Code CLI with KiosAPI as the API backend, routing your terminal coding sessions through KiosAPI's unified gateway.

Anthropic's Claude Code is an agentic coding tool that runs directly in your terminal. This tutorial walks you through installing Claude Code, pointing it at KiosAPI, and verifying that your setup is working — so you can start coding with Claude models through KiosAPI's unified API gateway.

## Prerequisites

* **Node.js 18+** — verify with `node --version`
* A **KiosAPI API key** (starts with `sk-`) from the [Dashboard](https://kiosapi.com) → **Token Management**

<Steps>
  ### Install Claude Code

  Install the Claude Code CLI globally via npm:

  ```bash theme={null}
  npm install -g @anthropic-ai/claude-code
  ```

  Verify the installation succeeded:

  ```bash theme={null}
  claude --version
  ```

  ### Get your KiosAPI key

  1. Log in to the [KiosAPI Dashboard](https://kiosapi.com)
  2. Navigate to **Token Management**
  3. Create or copy an existing API key (starts with `sk-`)

  <Tip>
    Use the **`claude_cc`** token group for Claude Code — it routes to Claude endpoints optimized for coding tasks and is cheaper than the default group.
  </Tip>

  ### Skip the onboarding wizard

  After installing, skip the interactive onboarding wizard by editing `~/.claude.json`:

  ```json theme={null}
  {
    "hasCompletedOnboarding": true
  }
  ```

  This prevents Claude Code from prompting you to sign in with an Anthropic account.

  ### Configure your project

  Create a `.claude/settings.json` file in your project root to inject the KiosAPI environment variables:

  ```json theme={null}
  {
    "env": {
      "ANTHROPIC_BASE_URL": "https://kiosapi.com",
      "ANTHROPIC_AUTH_TOKEN": "sk-xxx",
      "ANTHROPIC_MODEL": "claude-sonnet-4-6",
      "ANTHROPIC_SMALL_FAST_MODEL": "claude-haiku-4-5-20251001",
      "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
    }
  }
  ```

  Replace `sk-xxx` with your actual KiosAPI key.

  <Info>
    Set `ANTHROPIC_BASE_URL` to `https://kiosapi.com` — without `/v1`. Claude Code appends the API path automatically.
  </Info>

  ### (Optional) Set global environment variables

  To make Claude Code work in any directory, set the variables globally instead of per-project.

  <Tabs>
    <Tab title="macOS / Linux">
      Add the following lines to `~/.bashrc` or `~/.zshrc`:

      ```bash theme={null}
      export ANTHROPIC_BASE_URL="https://kiosapi.com"
      export ANTHROPIC_AUTH_TOKEN="sk-xxx"
      export ANTHROPIC_MODEL="claude-sonnet-4-6"
      export ANTHROPIC_SMALL_FAST_MODEL="claude-haiku-4-5-20251001"
      export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS="1"
      ```

      Then reload your shell:

      ```bash theme={null}
      source ~/.bashrc  # or ~/.zshrc
      ```
    </Tab>

    <Tab title="Windows (PowerShell)">
      ```powershell theme={null}
      setx ANTHROPIC_BASE_URL "https://kiosapi.com"
      setx ANTHROPIC_AUTH_TOKEN "sk-xxx"
      setx ANTHROPIC_MODEL "claude-sonnet-4-6"
      setx ANTHROPIC_SMALL_FAST_MODEL "claude-haiku-4-5-20251001"
      setx CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS "1"
      ```
    </Tab>
  </Tabs>

  The global config file is located at:

  | Platform | Path                               |
  | -------- | ---------------------------------- |
  | Windows  | `C:\Users\<username>\.claude.json` |
  | macOS    | `/Users/<username>/.claude.json`   |
  | Linux    | `/home/<username>/.claude.json`    |

  ### Verify your setup

  Navigate to your project directory and run a quick test:

  ```bash theme={null}
  claude "Say hello"
  ```

  If Claude responds, your configuration is working correctly. Launch a full interactive session with:

  ```bash theme={null}
  claude
  ```
</Steps>

## Best Practices

### CLAUDE.md

Create a `CLAUDE.md` file in your project root to give Claude persistent context about your codebase, conventions, and common commands. Claude Code reads this file automatically on startup.

### File permissions

Claude Code asks for permission before reading or writing files. You can pre-approve directories by adding them to `.claude/settings.json`:

```json theme={null}
{
  "permissions": {
    "allow": ["Read(*)", "Write(src/**)", "Edit(src/**)"]
  }
}
```

### Context management

Long sessions can consume a lot of context. Use these slash commands to manage it:

| Command    | Description                                                |
| ---------- | ---------------------------------------------------------- |
| `/clear`   | Clears the entire conversation history                     |
| `/compact` | Summarizes and compresses the conversation to save context |

## Switching Models

Change the default model globally with the Claude Code config command:

```bash theme={null}
claude config set --global env '{"ANTHROPIC_MODEL": "claude-opus-4-6"}'
```

Or switch to a lighter model for faster responses:

```bash theme={null}
claude config set --global env '{"ANTHROPIC_MODEL": "claude-haiku-4-5-20251001"}'
```

## Troubleshooting

### 400 Bad Request / Invalid beta flag

If you see an error like `Invalid beta flag` or a `400` status code:

```text theme={null}
Error: Invalid beta flag: claude-3-5-sonnet-20241022
```

Make sure `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` is set to `"1"` in your configuration. This disables experimental beta headers that KiosAPI may not support.

### Output length / max tokens error

If you get an error about output length or max tokens exceeded:

```text theme={null}
Error: output length exceeded
```

Add the following to your `.claude/settings.json` env block:

```json theme={null}
"CLAUDE_CODE_MAX_OUTPUT_TOKENS": "32000"
```

### 401 Unauthorized / Connection refused

* Verify your API key is correct and starts with `sk-`
* Ensure `ANTHROPIC_BASE_URL` is `https://kiosapi.com` — no trailing slash, no `/v1`
* Check that your token group supports Claude models (use `claude_cc`)

## Need Help?

* [KiosAPI Dashboard](https://kiosapi.com)
* [Token Management Guide](/token-management/quota)
* [Available Models](../api-reference/models/list-models)