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

# Claude Code

> Use AIOHub as the model provider in Claude Code.

[Claude Code](https://www.anthropic.com/claude-code) uses the Anthropic Messages API. Set `ANTHROPIC_BASE_URL` to the AIOHub gateway root; Claude Code appends `/v1/messages` itself.

## Prerequisites

* Claude Code installed with Node.js 18+
* An AIOHub `sk-` API key
* A group assigned to the API key that can access Claude-compatible models
* A positive account balance

## Temporary setup

Set the variables in the shell where you start Claude Code:

```bash theme={"system"}
export ANTHROPIC_BASE_URL="https://api.aiohub.org"
export ANTHROPIC_AUTH_TOKEN="sk-your-api-key"
export ANTHROPIC_MODEL="claude-sonnet-4-20250514"
claude
```

<Note>Do not add `/v1` to `ANTHROPIC_BASE_URL`. Set `ANTHROPIC_AUTH_TOKEN` to the full `sk-` API key value, without a manual `Bearer ` prefix; Claude Code sends it with Authorization Bearer authentication.</Note>

## Persistent setup

Add the variables to your shell profile:

<Tabs>
  <Tab title="macOS / Linux (zsh)">
    ```bash theme={"system"}
    echo 'export ANTHROPIC_BASE_URL="https://api.aiohub.org"' >> ~/.zshrc
    echo 'export ANTHROPIC_AUTH_TOKEN="sk-your-api-key"' >> ~/.zshrc
    echo 'export ANTHROPIC_MODEL="claude-sonnet-4-20250514"' >> ~/.zshrc
    source ~/.zshrc
    ```
  </Tab>

  <Tab title="macOS / Linux (bash)">
    ```bash theme={"system"}
    echo 'export ANTHROPIC_BASE_URL="https://api.aiohub.org"' >> ~/.bashrc
    echo 'export ANTHROPIC_AUTH_TOKEN="sk-your-api-key"' >> ~/.bashrc
    echo 'export ANTHROPIC_MODEL="claude-sonnet-4-20250514"' >> ~/.bashrc
    source ~/.bashrc
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={"system"}
    [System.Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.aiohub.org", "User")
    [System.Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-your-api-key", "User")
    [System.Environment]::SetEnvironmentVariable("ANTHROPIC_MODEL", "claude-sonnet-4-20250514", "User")
    ```
  </Tab>
</Tabs>

You can also store the same values in Claude Code settings:

```json theme={"system"}
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.aiohub.org",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-api-key",
    "ANTHROPIC_MODEL": "claude-sonnet-4-20250514"
  }
}
```

User settings live at `~/.claude/settings.json`. Project-local private settings can live at `.claude/settings.local.json`; do not commit real API keys.

### Optional: 1-hour prompt caching

Claude API prompt caching uses a 5-minute TTL by default. If you often resume long Claude Code sessions, work with large repository context, or reuse the same long prompt prefix after more than 5 minutes, add `ENABLE_PROMPT_CACHING_1H` to the `env` block in `~/.claude/settings.json` to request a 1-hour TTL:

```json theme={"system"}
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.aiohub.org",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-api-key",
    "ANTHROPIC_MODEL": "claude-sonnet-4-20250514",
    "ENABLE_PROMPT_CACHING_1H": "1"
  }
}
```

<Note>Use the 1-hour TTL for sessions that repeatedly reuse long context. In Anthropic pricing, 1-hour cache writes are charged at 2x the base input token price, while cache reads are cheaper; if you typically resume within 5 minutes, the default cache is enough.</Note>

### Optional: disable attribution header

Claude Code prepends a dynamic attribution header (containing the client version and prompt fingerprint) to the system prompt on every request. When routing through a gateway, this changing prefix invalidates the KV cache and slows down inference.

Set `CLAUDE_CODE_ATTRIBUTION_HEADER` to `"0"` in `~/.claude/settings.json` to omit this dynamic block and improve prompt cache hit rates:

```json theme={"system"}
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.aiohub.org",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-api-key",
    "ANTHROPIC_MODEL": "claude-sonnet-4-20250514",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
  }
}
```

<Note>This only affects caching on the gateway side. Anthropic's own prompt caching is unaffected. If you connect directly to the Anthropic API without a gateway, you do not need this setting.</Note>

### Command alias

You can create a shell alias when you want a separate command for AIOHub-backed Claude Code:

```bash theme={"system"}
alias mycc="ANTHROPIC_BASE_URL=https://api.aiohub.org ANTHROPIC_AUTH_TOKEN=sk-your-api-key ANTHROPIC_MODEL=claude-sonnet-4-20250514 claude"
```

Run `mycc` to start Claude Code with the AIOHub environment.

## Verify

Start Claude Code and send a short prompt. You can first confirm that the command is available:

```bash theme={"system"}
claude --version
```

To verify the environment without printing the API key value:

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={"system"}
    test "$ANTHROPIC_BASE_URL" = "https://api.aiohub.org" && echo "base url ok"
    test -n "$ANTHROPIC_AUTH_TOKEN" && echo "api key configured"
    test -n "$ANTHROPIC_MODEL" && echo "model configured"
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={"system"}
    if ($Env:ANTHROPIC_BASE_URL -eq "https://api.aiohub.org") { "base url ok" }
    if ($Env:ANTHROPIC_AUTH_TOKEN) { "api key configured" }
    if ($Env:ANTHROPIC_MODEL) { "model configured" }
    ```
  </Tab>
</Tabs>

### Session commands

Inside a Claude Code session, these commands help locate client state:

| Command    | Use                                            |
| ---------- | ---------------------------------------------- |
| `/status`  | View current session status                    |
| `/context` | Inspect context token usage                    |
| `/clear`   | Clear the current conversation and start fresh |
| `/model`   | View or change the selected model              |

## Protocol notes

Claude Code sends Anthropic Messages requests, normally `POST /v1/messages`. The Base URL must therefore be `https://api.aiohub.org`, not `https://api.aiohub.org/v1`. When testing manually with `curl`, include the full path and the Anthropic version header:

```bash theme={"system"}
curl https://api.aiohub.org/v1/messages \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 128,
    "messages": [{"role": "user", "content": "Hello from AIOHub"}]
  }'
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Claude Code keeps asking you to log in">
    Check that the shell you launched Claude Code from has `ANTHROPIC_AUTH_TOKEN`. If `ANTHROPIC_API_KEY` is also set, Claude Code may use API-key mode; AIOHub setup should use `ANTHROPIC_AUTH_TOKEN`.

    If you store configuration in `settings.json`, you can add `apiKeyHelper`:

    ```json theme={"system"}
    {
      "apiKeyHelper": "echo 'sk-your-api-key'",
      "env": {
        "ANTHROPIC_BASE_URL": "https://api.aiohub.org",
        "ANTHROPIC_AUTH_TOKEN": "sk-your-api-key",
        "ANTHROPIC_MODEL": "claude-sonnet-4-20250514"
      }
    }
    ```
  </Accordion>

  <Accordion title="404 or API Connect Error">
    Confirm `ANTHROPIC_BASE_URL` does not include `/v1`. If it is `https://api.aiohub.org/v1`, Claude Code can end up calling `/v1/v1/messages`.
  </Accordion>

  <Accordion title="The request returns 400">
    Clear the current conversation with `/clear`, then retry with a fresh prompt. Also confirm that the selected model exists in the group assigned to your API key. If the error is related to Claude Code experimental features, start Claude Code with `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` and retry.
  </Accordion>

  <Accordion title="Context is too large or the session becomes slow">
    Use `/context` to inspect context usage. If needed, clear the conversation, start a new session, or reduce long history before automatic compaction.
  </Accordion>

  <Accordion title="Insufficient balance">
    Open [wallet management](https://api.aiohub.org/console/topup) to view balance and add funds.
  </Accordion>
</AccordionGroup>

## Official references

* [Claude Code environment variables](https://code.claude.com/docs/en/env-vars)
* [Claude Code settings](https://code.claude.com/docs/en/settings)
* [Anthropic prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#ttl-support)