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

# Claude Code Setup Guide

> Configure Claude Code with LaoZhang API using settings.json, current recommended Claude models, and the AWS Claude / Bedrock 400 compatibility fix.

## Overview

Claude Code is Anthropic's official command-line coding assistant. It is designed for local project work such as code generation, debugging, refactoring, tests, and documentation. With LaoZhang API configured, you can use Claude models directly from the terminal without moving project work into a web UI.

<CardGroup cols={2}>
  <Card title="Local CLI Agent" icon="terminal">
    Runs inside your project directory and fits terminal-based workflows.
  </Card>

  <Card title="Claude Code Token Group" icon="key">
    Select the Claude Code group when creating the token to avoid route mismatch.
  </Card>

  <Card title="Current Model Set" icon="brain">
    Use Sonnet 4.6 by default and switch to Opus 4.7 for harder tasks.
  </Card>

  <Card title="AWS Route Compatibility" icon="shield-check">
    Disables experimental beta fields to reduce Bedrock 400 validation errors.
  </Card>
</CardGroup>

<Note>
  This page only lists the recommended models for new Claude Code setups. Legacy Opus / Sonnet 4.5, 4.1, and 3.x models are no longer recommended for new configurations. Check the console for the actual selectable models.
</Note>

## Required: AWS Claude 400 Compatibility Setting

<Warning>
  If Claude Code returns `400 ValidationException`, `Extra inputs are not permitted`, or errors related to `cache_control.scope` on the AWS Claude official route, first disable Claude Code experimental beta request fields.
</Warning>

For the current terminal session, run this before starting Claude Code:

```bash theme={null}
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
```

For persistent configuration, add it to `~/.claude/settings.json`:

```json theme={null}
{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}
```

## Quick Setup

<Steps>
  <Step title="Install Claude Code">
    Run:

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

    Node.js 18 or higher is required. If it is not installed, download it from [nodejs.org](https://nodejs.org).
  </Step>

  <Step title="Create a Claude Code Token">
    Open the [LaoZhang API Console](https://api2.laozhang.ai/token), create a new token, select the Claude Code group, and copy the `sk-...` key.

    <Warning>
      The token must be created under the Claude Code group. Other Claude groups may not work correctly with Claude Code.
    </Warning>
  </Step>

  <Step title="Write settings.json">
    Edit `~/.claude/settings.json`:

    ```bash theme={null}
    vim ~/.claude/settings.json
    ```

    Recommended configuration:

    ```json theme={null}
    {
      "env": {
        "ANTHROPIC_BASE_URL": "https://api2.laozhang.ai",
        "ANTHROPIC_AUTH_TOKEN": "sk-your-laozhang-api-key",
        "ANTHROPIC_MODEL": "claude-sonnet-4-6",
        "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
      }
    }
    ```

    <Tip>
      `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` disables Claude Code experimental beta request fields for better AWS Claude / Bedrock compatibility.
    </Tip>
  </Step>

  <Step title="Launch Claude Code">
    Navigate to your project directory and start:

    ```bash theme={null}
    cd ~/Desktop/my-project
    claude
    ```

    On first launch, Claude Code shows the API configuration. Confirm the Base URL, token, and model before continuing.
  </Step>
</Steps>

## Model Selection

For new projects, choose from the models below and avoid carrying over legacy Opus / Sonnet 4.5, 4.1, or 3.x model IDs from older configs.

| Use Case                              | Recommended Model ID         | Guidance                                                                      |
| ------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------- |
| Default daily development             | `claude-sonnet-4-6`          | Balanced quality, speed, and cost for most coding work                        |
| Everyday reasoning-heavy work         | `claude-sonnet-4-6-thinking` | Good for code review, bug analysis, and implementation planning               |
| Difficult agentic coding              | `claude-opus-4-7`            | Best for large refactors, cross-module design, and long coding workflows      |
| Deep analysis and multi-step planning | `claude-opus-4-7-thinking`   | Use for high-risk migrations, architecture choices, and complex decomposition |
| Fast low-cost tasks                   | `claude-haiku-4-5`           | Good for short questions, simple scripts, docs polish, and quick responses    |

<Tip>
  Start with `claude-sonnet-4-6`. Switch to Opus 4.7 only when the task needs stronger planning, longer context, or complex tool use.
</Tip>

## Usage

### Basic Command

```bash theme={null}
claude
# Shows API Key, Base URL, and model configuration
# Confirm the configuration and continue
```

### Common Workflow

1. Run `claude` in the project directory
2. Describe the file, error, or goal
3. Ask Claude Code for a plan first
4. Let it edit files, run commands, or generate tests after confirmation

### Good Fit

<CardGroup cols={2}>
  <Card title="Code Generation and Refactoring" icon="code">
    Generate functions, refactor modules, and adjust project structure.
  </Card>

  <Card title="Bug Fixing and Debugging" icon="bug">
    Analyze errors, locate causes, and add regression checks.
  </Card>

  <Card title="Tests and Scripts" icon="flask-conical">
    Write tests, maintain scripts, and automate project commands.
  </Card>

  <Card title="Docs and Explanations" icon="file-text">
    Produce README updates, API notes, and changelog entries.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="400 ValidationException / Extra inputs are not permitted">
    If Claude Code returns one of the following errors, Claude Code may be sending experimental beta parameters that are not accepted by AWS Claude / Bedrock:

    * `400 ValidationException`
    * `Extra inputs are not permitted`
    * Errors related to `cache_control.scope`

    Recommended order:

    1. Update Claude Code to the latest version.
    2. Set `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`.

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

    The [official Claude LLM gateway documentation](https://code.claude.com/docs/en/llm-gateway) notes that when using the Anthropic Messages format with Bedrock or Vertex, you may need to set `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`. Without it, some beta parameters or request fields may trigger gateway or Bedrock validation errors.

    Add this setting under `env` in `~/.claude/settings.json`:

    ```json theme={null}
    {
      "env": {
        "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
      }
    }
    ```

    To apply it only to the current terminal session, run:

    ```bash theme={null}
    export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
    ```

    To make it permanent, add it to your shell profile:

    ```bash theme={null}
    # macOS / Linux bash
    echo 'export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1' >> ~/.bashrc
    source ~/.bashrc

    # macOS default zsh
    echo 'export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1' >> ~/.zshrc
    source ~/.zshrc
    ```

    On Windows PowerShell, run:

    ```powershell theme={null}
    [System.Environment]::SetEnvironmentVariable("CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS", "1", "User")
    ```

    Reopen the terminal and restart Claude Code after changing the setting. This forces Claude Code to use a more standard request shape and avoids unsupported fields such as `cache_control`, extended `tool` fields, and `scope` being rejected by Bedrock.

    If the error continues, check whether the model name is correct, whether you are sending a custom request body, and whether a non-standard SDK is involved. When contacting support, provide the error screenshot, Request ID, and model name.
  </Accordion>

  <Accordion title="Unable to Connect to Anthropic Services">
    This is usually a Base URL, token, model name, or network configuration issue. First check that `~/.claude/settings.json` contains these fields:

    * `ANTHROPIC_BASE_URL`
    * `ANTHROPIC_AUTH_TOKEN`
    * `ANTHROPIC_MODEL`

    If you inject configuration through terminal environment variables instead of `settings.json`, then use `echo` to check whether the current terminal can read those variables. Do not share screenshots that expose the full token.
  </Accordion>

  <Accordion title="Requires Claude Account Authorization">
    If Claude Code still asks for official account authorization, create `.claude.json` in the project directory:

    ```json theme={null}
    {
      "apiKey": "sk-your-laozhang-api-key",
      "apiBaseUrl": "https://api2.laozhang.ai",
      "hasCompletedOnboarding": true
    }
    ```

    This is useful when a project needs fixed local configuration. Keep the main global configuration in `~/.claude/settings.json`.
  </Accordion>

  <Accordion title="Invalid API Key or Wrong Token Group">
    Make sure you are using a LaoZhang API key and that the token was created under the Claude Code group. You can regenerate the token in the [LaoZhang API Console](https://api2.laozhang.ai/token) and test again.
  </Accordion>

  <Accordion title="How to Update Claude Code">
    Run:

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

    Reopen the terminal after updating, then run `claude` again.
  </Accordion>
</AccordionGroup>

## Best Practices

| Recommendation                    | Details                                                                       |
| --------------------------------- | ----------------------------------------------------------------------------- |
| Use Sonnet 4.6 by default         | Balanced cost and quality for most daily development                          |
| Switch to Opus 4.7 for hard work  | Better fit for architecture changes, cross-file refactors, and long workflows |
| Ask for a plan before large edits | Review the plan before letting Claude Code modify files                       |
| Keep Git checks in the loop       | Use `git status`, `git diff`, and project tests before accepting changes      |
| Check pricing in the console      | Claude Code is token-metered; current pricing is shown in the console         |

## Related Resources

<CardGroup cols={2}>
  <Card title="Official Docs" icon="book" href="https://docs.anthropic.com/en/docs/claude-code/setup">
    Claude Code official documentation
  </Card>

  <Card title="API Console" icon="cog" href="https://api2.laozhang.ai/token">
    Manage API keys
  </Card>

  <Card title="Model Info" icon="bot" href="/en/api-capabilities/model-info">
    View current Claude models
  </Card>

  <Card title="Cline Setup" icon="code" href="/en/scenarios/programming/cline">
    VS Code AI agent setup
  </Card>
</CardGroup>

Need help? Visit [LaoZhang API](https://api2.laozhang.ai) for support.