Connect Claude Code to HeFu: Configuration, Model Selection, and Troubleshooting

Connecting a coding assistant to an API gateway requires agreement on four things: protocol, endpoint, authentication, and model selection.

This guide uses HeFu as the gateway and Claude Code as the client. We will configure the connection, test the API independently, and verify a small coding workflow.

What you will need

• Claude Code installed locally.
• A HeFu API key.
• A Claude model ID available through HeFu’s Anthropic-compatible API.
• A terminal with access to the API endpoint.

Replace every placeholder in the examples before running them.

1. Understand which API Claude Code uses

HeFu exposes multiple API formats. For this integration, Claude Code uses the Anthropic Messages API format.

An OpenAI Chat Completions request typically targets:

POST /v1/chat/completions

An Anthropic Messages request targets:

POST /v1/messages

These formats have different request and response structures. Changing the hostname does not translate one format into the other.

For this tutorial, the addresses are:

Claude Code base URL:
https://api.hefu.hk

Messages endpoint:
https://api.hefu.hk/v1/messages

Claude Code supplies the Messages API path. Do not set the base URL to the full /v1/messages endpoint.

Also, do not automatically reuse the versioned base URL from an OpenAI SDK configuration. Check the final request path to avoid duplicating /v1.

2. Install and verify Claude Code

If Claude Code is already installed, check the version:

claude --version

For a new installation on macOS, Linux, or WSL:

curl -fsSL https://claude.ai/install.sh | bash

On Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

After installation, open a new terminal and run:

claude --version

For installation diagnostics:

claude doctor

These checks verify the local installation. They do not verify the gateway connection.

3. Configure the connection

The connection uses three environment variables:

• ANTHROPIC_BASE_URL: where model requests are sent.
• ANTHROPIC_AUTH_TOKEN: the gateway credential.
• ANTHROPIC_MODEL: the selected model.

Copy the exact model ID from HeFu’s model directory or console. A product display name is not necessarily the identifier accepted by the API.

Bash or Zsh

export ANTHROPIC_BASE_URL="https://api.hefu.hk"
export ANTHROPIC_AUTH_TOKEN="YOUR_HEFU_API_KEY"
export ANTHROPIC_MODEL="YOUR_HEFU_CLAUDE_MODEL_ID"

Windows PowerShell

$env:ANTHROPIC_BASE_URL="https://api.hefu.hk"
$env:ANTHROPIC_AUTH_TOKEN="YOUR_HEFU_API_KEY"
$env:ANTHROPIC_MODEL="YOUR_HEFU_CLAUDE_MODEL_ID"

The bearer-token configuration follows HeFu’s Claude Code integration example.

Claude Code sends ANTHROPIC_AUTH_TOKEN through the Authorization: Bearer header. ANTHROPIC_API_KEY uses the x-api-key header, so these variables are not interchangeable.

Start with configuration in one terminal session. Launch Claude Code from that same terminal so it inherits the variables.

4. Test the API before testing the client

A direct request helps separate gateway connectivity from Claude Code configuration.

Start with a small non-streaming text request.

Bash or Zsh

curl --silent --show-error \
  --max-time 60 \
  --write-out '\nHTTP status: %{http_code}\n' \
  "${ANTHROPIC_BASE_URL}/v1/messages" \
  -H "Authorization: Bearer ${ANTHROPIC_AUTH_TOKEN}" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  --data "{
    \"model\": \"${ANTHROPIC_MODEL}\",
    \"max_tokens\": 64,
    \"messages\": [
      {
        \"role\": \"user\",
        \"content\": \"Reply with a short greeting.\"
      }
    ]
  }"

Windows PowerShell

$headers = @{
    Authorization = "Bearer $env:ANTHROPIC_AUTH_TOKEN"
    "anthropic-version" = "2023-06-01"
}

$body = @{
    model = $env:ANTHROPIC_MODEL
    max_tokens = 64
    messages = @(
        @{
            role = "user"
            content = "Reply with a short greeting."
        }
    )
} | ConvertTo-Json -Depth 10

$response = Invoke-RestMethod `
    -Method Post `
    -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
    -Headers $headers `
    -ContentType "application/json" `
    -Body $body

$response | ConvertTo-Json -Depth 20

Inspect both the HTTP status and the response body.

A successful Messages API response should contain a content array. An HTML login page or proxy error page is not a successful model response.

This test verifies basic text generation. Streaming, tool calls, and repository tasks still need separate verification.

5. Launch Claude Code with an explicit model

On macOS, Linux, or WSL:

claude --model "$ANTHROPIC_MODEL"

On Windows PowerShell:

claude --model "$env:ANTHROPIC_MODEL"

Using --model makes the selected model explicit for this launch.

Inside the interactive session, run:

/status

Check that:

• The Anthropic base URL points to HeFu.
• The credential source matches the configured token.
• The selected model matches your intended model.

Then send a small prompt:

Reply with a short greeting. Do not read or modify any files.

Changing the base URL determines the destination. It does not automatically choose the model.

6. Verify a coding workflow

A greeting confirms basic generation. A coding assistant also needs to read files, use tools, and incorporate their results.

Create a small project containing slugify.py:

import re


def slugify(text):
    text = text.strip().lower()
    text = re.sub(r"[^a-z0-9]+", "-", text)
    return text.strip("-")

Start Claude Code from that directory and use this prompt:

text
Read slugify.py and explain its current behavior.

Then create test_slugify.py using Python's built-in unittest module.

Cover:
- Leading and trailing whitespace
- Repeated spaces
- Punctuation between words
- Empty input
- Input containing only punctuation

Do not modify slugify