# Claude / Claude Code Configuration

Claude Code is Anthropic's official terminal command-line AI coding assistant. Connect it through the 4AICode API to manage keys, team quotas, and usage in one console, with billing based on actual token usage.

> 💡 **Beginner tip**: We recommend starting with **[Method 1: Quick Script Installation & Setup]**. A single command handles everything automatically, saving time and effort.

**About Route Selection**:
4AICode provides two interchangeable network routes with shared accounts and tokens:
- **International Route (Recommended for global users)**: Uses `https://relay.4aicode.com`.
- **Mainland China Direct Route**: Uses `https://relay.4aicode.net` (more stable for direct connections in mainland China).

---

## Prerequisites: Get Your Token

Whichever setup method you choose, you first need your 4AICode token:

1. Sign in to 4AICode and go to [Dashboard → Manage Tokens](https://4aicode.com/tokens) (or [4aicode.net/tokens](https://4aicode.net/tokens) in mainland China).
2. Click **"New Token"**.
3. Copy the generated string (formatted like `sk-4ai-<your-token>`).

> ⚠️ **Important security notes**:
> - The token is shown only once upon creation. Save it to a password manager or notes app.
> - All `sk-4ai-<your-token>` strings in this guide are placeholders. Replace them with your actual token.
> - Treat your token like a password: never share it or commit it to GitHub. Tokens typed directly into shell commands remain in terminal history; clear your history if necessary (e.g. by running `history -c` or clearing the terminal history file).

---

## Method 1: Quick Script Installation & Setup (Recommended for Beginners)

Select the tab matching your operating system:


**macOS / Linux**


### 1. Open Terminal
Press `⌘ + Space`, type "Terminal", and press Enter.

### 2. Install Claude Code CLI
Claude Code requires Node.js 18+. Run the official one-click installer in your terminal:

```bash
# Official installer command
curl -fsSL https://claude.ai/install.sh | bash
```

After installation, run `claude --version`. Seeing a version number confirms installation succeeded.

### 3. Configure 4AICode Environment Variables
Write the environment variables to your shell configuration file so they persist across terminal sessions. Replace `sk-4ai-<your-token>` with your actual token:

```bash
# International route (recommended for overseas/global network)
cat <<'EOF' >> ~/.zshrc
export ANTHROPIC_BASE_URL=https://relay.4aicode.com
export ANTHROPIC_AUTH_TOKEN=sk-4ai-<your-token>
export ANTHROPIC_API_KEY=sk-4ai-<your-token>
EOF
source ~/.zshrc

# Note: If you use bash instead of zsh (e.g., on some Linux distros), replace ~/.zshrc with ~/.bashrc
```

*For mainland China direct route, simply replace `https://relay.4aicode.com` above with `https://relay.4aicode.net`.*

### 4. Verify Setup
**Open a new terminal window** (to load the latest configuration), navigate to any project directory, and run:

```bash
claude
```
Once in the conversation interface, test it with: `Hello, please explain the current project structure`. Getting a proper response confirms you are successfully connected to 4AICode!


**Windows**


### 1. Open PowerShell
Press the `Win key`, search for and open **PowerShell** (or Windows Terminal).

### 2. Run Automated Setup Script
4AICode provides an automated PowerShell script that automatically detects and installs Node.js, npm, Git, and Claude Code, completing 4AICode configuration in one step.

**Interactive setup (recommended)**: Prompts you to paste your token:

```powershell
irm https://4aicode.com/claude-install.ps1 | iex
```

**Unattended setup**: Directly pass your token:

```powershell
& ([scriptblock]::Create((irm https://4aicode.com/claude-install.ps1))) -ApiKey 'sk-4ai-<your-token>'
```

*For mainland China direct route, use `https://4aicode.net/claude-install.ps1` instead.*

### 3. Verify Setup
**Open a new PowerShell window**, navigate to your project directory, and run:

```powershell
claude
```
Send a test message to start coding!


---

## Method 2: Global Configuration File (Cleaner Approach)

In addition to environment variables, Claude Code supports global configuration via `settings.json`. This approach keeps your shell environment clean and persists reliably.

Configuration file path:
- **macOS / Linux**: `~/.claude/settings.json`
- **Windows**: `%USERPROFILE%\.claude\settings.json`

Open or create this file, and insert the configuration under the `env` key (if existing settings are present, preserve them and merge the `env` object):

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://relay.4aicode.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-4ai-<your-token>",
    "ANTHROPIC_API_KEY": "sk-4ai-<your-token>"
  }
}
```

Save and restart your terminal or Claude Code for the changes to take effect.

---

## Advanced: Using Other Top-Tier Models in Claude Code

The 4AICode backend gateway provides intelligent model routing. You can use Claude Code's polished terminal interface while running ChatGPT (GPT-5.6 / GPT-6) or Kimi K3 under the hood!

### 0. Using Claude Opus 5.5 Kiro in Claude Code (Best Value)

**Claude Opus 5.5 Kiro** is 4AICode's exclusive Claude Code-optimized version, offering exceptional value with discounted pricing.


**macOS / Linux**


```bash
# Using Claude Opus 5.5 Kiro (Recommended)
export ANTHROPIC_BASE_URL=https://relay.4aicode.com
export ANTHROPIC_AUTH_TOKEN=sk-4ai-<your-token>
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5-kiro
export ANTHROPIC_MODEL=opus
claude
```


**Windows**


```powershell
# Using Claude Opus 5.5 Kiro (Recommended)
[Environment]::SetEnvironmentVariable('ANTHROPIC_BASE_URL', 'https://relay.4aicode.com', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_AUTH_TOKEN', 'sk-4ai-<your-token>', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_DEFAULT_OPUS_MODEL', 'claude-opus-5-5-kiro', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_MODEL', 'opus', 'User')
```


**Use Cases**:
- Complex code generation and architecture design
- Multi-step reasoning and problem solving
- Large-scale context handling (200K tokens)
- Technical documentation writing and code review

### 1. Using ChatGPT Models in Claude Code

Simply set the model environment variables. When receiving `/v1/messages` requests, the gateway selects the upstream service corresponding to the requested `gpt-*` model:


**macOS / Linux**


```bash
# Recommended daily driver: GPT-5.6 Terra
export ANTHROPIC_BASE_URL=https://relay.4aicode.com
export ANTHROPIC_AUTH_TOKEN=sk-4ai-<your-token>
export ANTHROPIC_DEFAULT_OPUS_MODEL=gpt-5.6-terra
export ANTHROPIC_MODEL=opus
claude

# Top-tier flagship: GPT-6 Astra
export ANTHROPIC_DEFAULT_OPUS_MODEL=gpt-6-astra
export ANTHROPIC_MODEL=opus
claude

# Complex architecture & deep reasoning: GPT-5.6 Sol with ultra-high reasoning
export ANTHROPIC_BASE_URL=https://relay.4aicode.com
export ANTHROPIC_AUTH_TOKEN=sk-4ai-<your-token>
export ANTHROPIC_DEFAULT_OPUS_MODEL=gpt-5.6-sol
export ANTHROPIC_DEFAULT_OPUS_MODEL_NAME="4AICode GPT 5.6 Sol"
export ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES=effort,xhigh_effort,thinking,adaptive_thinking,interleaved_thinking
export ANTHROPIC_MODEL=opus
export ANTHROPIC_DEFAULT_HAIKU_MODEL=gpt-5.4-mini
export CLAUDE_CODE_EFFORT_LEVEL=xhigh
claude
```


**Windows**


```powershell
# Recommended daily driver: GPT-5.6 Terra
[Environment]::SetEnvironmentVariable('ANTHROPIC_BASE_URL', 'https://relay.4aicode.com', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_AUTH_TOKEN', 'sk-4ai-<your-token>', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_DEFAULT_OPUS_MODEL', 'gpt-5.6-terra', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_MODEL', 'opus', 'User')

# Top-tier flagship: GPT-6 Astra
[Environment]::SetEnvironmentVariable('ANTHROPIC_DEFAULT_OPUS_MODEL', 'gpt-6-astra', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_MODEL', 'opus', 'User')
```


### 2. Using Kimi K3 in Claude Code (Ultra-Long 1M Context)
If you need to analyze massive codebases or large documentation sets, connect Kimi K3. See the dedicated guide:
👉 [Detailed Guide: Using Kimi K3 with Claude Code](/docs/en/guides/claude-kimi)

---

## Other Tools & SDK Integration

4AICode is fully compatible with official Anthropic API specifications, enabling seamless integration with any Anthropic-supported SDK or tool:

### 1. Unified Connection Parameters
- **Base URL**: `https://relay.4aicode.com` (use `https://relay.4aicode.net` in mainland China)
- **API Key / Token**: Your 4AICode Token (`sk-4ai-<your-token>`)

### 2. Node.js / TypeScript SDK

```ts
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://relay.4aicode.com",
  apiKey: "sk-4ai-<your-token>",
});

const msg = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(msg.content);
```

### 3. Python SDK

```python
import anthropic

client = anthropic.Anthropic(
    base_url="https://relay.4aicode.com",
    api_key="sk-4ai-<your-token>",
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, please write a quicksort algorithm."}
    ]
)

print(message.content[0].text)
```

### 4. cURL Request Example

4AICode supports both the Anthropic official `x-api-key` header and the standard `Authorization: Bearer` header:

```bash
# Option A: Using x-api-key (Anthropic standard)
curl https://relay.4aicode.com/v1/messages \
  -H "x-api-key: sk-4ai-<your-token>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 128,
    "messages": [{"role": "user", "content": "ping"}]
  }'

# Option B: Using Authorization: Bearer
curl https://relay.4aicode.com/v1/messages \
  -H "Authorization: Bearer sk-4ai-<your-token>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 128,
    "messages": [{"role": "user", "content": "ping"}]
  }'
```

---

## Frequently Asked Questions (FAQ)

### Q1: `claude: command not found` or command unrecognized?
- **Cause**: Claude Code is not installed, or your terminal PATH environment variable has not updated.
- **Fix**: Completely close and reopen your terminal. If the issue persists:
  - macOS/Linux: Re-run the official installer `curl -fsSL https://claude.ai/install.sh | bash` and ensure `~/.local/bin` is in your `PATH`.
  - Windows: Run the setup script in PowerShell: `irm https://4aicode.com/claude-install.ps1 | iex`, which automatically configures PATH.

### Q2: Encountered `401 Unauthorized` or invalid token?
- **Cause**: Token string is incorrect, missing characters during copying, or placeholder was not replaced.
- **Fix**: Visit [Dashboard → Manage Tokens](https://4aicode.com/tokens) to inspect or recreate your token. Ensure it begins with `sk-4ai-`.

### Q3: Why didn't environment variable or settings.json changes take effect?
- **Cause**: The current terminal process has cached previous variables, or `settings.json` takes priority over environment variables.
- **Fix**: Completely exit the running Claude session and restart the terminal. Note that `settings.json` values override terminal environment variables.

### Q4: Common HTTP Error Codes

| Status Code | Cause | Resolution |
|---|---|---|
| **401** | Token invalid, expired, or revoked | Recreate token in dashboard and update configuration |
| **403** | Team or organization access suspended | Contact administrator to verify account status |
| **429** | Rate limit or quota exhausted | Check `X-RateLimit-*` headers; see [Rate Limits](/docs/en/guides/rate-limit) or top up balance |
| **503** | Upstream service temporarily unavailable or busy | Retry your request after a few seconds |