> ## 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 配置教程

> Claude Code 接入老张API配置教程：使用 settings.json 配置 API 地址、令牌、当前推荐 Claude 模型，并处理 AWS Claude / Bedrock 400 兼容问题。

## 工具简介

Claude Code 是 Anthropic 官方命令行编程助手，适合在本地项目中处理代码生成、调试、重构、测试和文档任务。通过老张API配置后，可以直接在终端里使用 Claude 系列模型，不需要把项目搬到网页端。

<CardGroup cols={2}>
  <Card title="本地命令行 Agent" icon="terminal">
    在项目目录中运行，保留本地文件和终端工作流。
  </Card>

  <Card title="Claude Code 专用分组" icon="key">
    创建令牌时选择「Claude Code」分组，避免普通 Claude 分组不兼容。
  </Card>

  <Card title="当前推荐模型" icon="brain">
    默认使用 Sonnet 4.6，复杂任务再切换到 Opus 4.7。
  </Card>

  <Card title="AWS 通道兼容" icon="shield-check">
    默认关闭实验性 Beta 字段，减少 Bedrock 400 参数错误。
  </Card>
</CardGroup>

<Note>
  本页只保留新项目推荐使用的 Claude Code 模型。旧版 Opus / Sonnet 4.5、4.1、3.x 型号不再作为新配置推荐，请以控制台实际可选模型为准。
</Note>

## 必做：AWS Claude 400 兼容设置

<Warning>
  如果 Claude Code 使用 AWS Claude 官方通道时遇到 `400 ValidationException`、`Extra inputs are not permitted` 或 `cache_control.scope` 相关错误，先关闭 Claude Code 实验性 Beta 请求字段。
</Warning>

临时生效只需要在启动 Claude Code 前执行这一行：

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

推荐把它写入 `~/.claude/settings.json`，避免每次打开终端都重新设置：

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

## 快速配置

<Steps>
  <Step title="安装 Claude Code">
    在终端运行：

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

    需要 Node.js 18 或更高版本。如未安装，请先访问 [nodejs.org](https://nodejs.org) 下载安装。
  </Step>

  <Step title="创建 Claude Code 分组令牌">
    访问 [老张API控制台](https://api2.laozhang.ai/token)，创建新令牌时选择「Claude Code」分组，然后复制 `sk-...` 格式的密钥。

    <Warning>
      创建令牌时必须选择「Claude Code」分组，否则 Claude Code 可能无法正常调用。
    </Warning>
  </Step>

  <Step title="写入 settings.json">
    编辑 `~/.claude/settings.json`：

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

    推荐配置如下：

    ```json theme={null}
    {
      "env": {
        "ANTHROPIC_BASE_URL": "https://api2.laozhang.ai",
        "ANTHROPIC_AUTH_TOKEN": "sk-你的老张API密钥",
        "ANTHROPIC_MODEL": "claude-sonnet-4-6",
        "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
      }
    }
    ```

    <Tip>
      `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` 用于关闭 Claude Code 实验性 Beta 请求字段，提升 AWS Claude / Bedrock 官方通道兼容性。
    </Tip>
  </Step>

  <Step title="启动 Claude Code">
    进入项目目录并启动：

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

    首次启动会显示 API 配置信息，确认 Base URL、Token 和模型无误后即可开始使用。
  </Step>
</Steps>

## 模型选择

新项目建议只在下表模型中选择，避免继续沿用旧配置里的 Opus / Sonnet 4.5、4.1 或 3.x 型号。

| 场景           | 推荐模型 ID                      | 选择建议                        |
| ------------ | ---------------------------- | --------------------------- |
| 日常开发默认模型     | `claude-sonnet-4-6`          | 速度、质量和成本更均衡，适合作为默认配置        |
| 日常复杂推理       | `claude-sonnet-4-6-thinking` | 适合需要更多分析步骤的代码审查、Bug 定位和方案设计 |
| 高难度 Agent 任务 | `claude-opus-4-7`            | 适合复杂重构、跨模块设计、长流程编码任务        |
| 深度分析与多步规划    | `claude-opus-4-7-thinking`   | 适合高风险迁移、架构决策和复杂问题拆解         |
| 快速低成本任务      | `claude-haiku-4-5`           | 适合短问题、简单脚本、文档润色和快速响应        |

<Tip>
  默认先用 `claude-sonnet-4-6`。只有当任务需要更强规划、长上下文或复杂工具调用时，再切换到 Opus 4.7。
</Tip>

## 使用方式

### 基本命令

```bash theme={null}
claude
# 显示 API Key、Base URL 和模型配置
# 确认配置无误后继续
```

### 常见工作流

1. 在项目目录运行 `claude`
2. 描述要处理的文件、错误或目标
3. 让 Claude Code 先给出修改计划
4. 确认后再让它修改文件、运行命令或生成测试

### 适合的任务

<CardGroup cols={2}>
  <Card title="代码生成与重构" icon="code">
    生成函数、重构模块、调整项目结构。
  </Card>

  <Card title="Bug 修复与调试" icon="bug">
    分析报错、定位问题、补充回归验证。
  </Card>

  <Card title="测试与脚本" icon="flask-conical">
    编写测试用例、维护脚本和自动化命令。
  </Card>

  <Card title="文档与说明" icon="file-text">
    生成 README、接口说明和变更记录。
  </Card>
</CardGroup>

## 故障排除

<AccordionGroup>
  <Accordion title="400 ValidationException / Extra inputs are not permitted">
    如果使用 Claude Code 时出现以下错误，通常是 Claude Code 默认启用了实验性 Beta 参数，而 AWS Claude / Bedrock 官方通道不接受这些额外字段：

    * `400 ValidationException`
    * `Extra inputs are not permitted`
    * `cache_control.scope` 相关错误

    处理顺序：

    1. 先升级 Claude Code 到最新版本。
    2. 再设置 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`。

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

    根据 [Claude 官方 LLM gateway 文档](https://code.claude.com/docs/en/llm-gateway)，使用 Anthropic Messages 格式连接 Bedrock 或 Vertex 时，可能需要设置 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`，否则部分 Beta 参数或请求字段可能导致网关/Bedrock 通道返回参数校验错误。

    推荐在 `~/.claude/settings.json` 的 `env` 中加入：

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

    如果只想让当前终端会话临时生效，可以执行：

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

    如需永久生效，请按你的终端环境写入配置文件：

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

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

    Windows PowerShell 可执行：

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

    设置完成后重新打开终端并运行 Claude Code。该开关会让请求结构回到更标准的格式，避免 `cache_control`、`tool` 扩展字段、`scope` 等参数在 Bedrock 通道被判定为非法字段。

    如果仍然报错，请继续检查模型名是否正确、是否存在自定义 request body、是否使用了非标准 SDK，并向客服提供报错截图、Request ID 和模型名称。
  </Accordion>

  <Accordion title="Unable to Connect to Anthropic Services">
    这通常是 Base URL、密钥、模型名或网络配置问题。请先检查 `~/.claude/settings.json` 里是否包含以下字段：

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

    如果你是通过终端环境变量注入配置，而不是通过 `settings.json`，再使用 `echo` 检查当前终端是否能读到对应变量。不要把包含完整密钥的截图公开发送。
  </Accordion>

  <Accordion title="提示需要 Claude 官网账号授权">
    如果 Claude Code 仍提示官网账号授权，可以在项目目录创建 `.claude.json`：

    ```json theme={null}
    {
      "apiKey": "sk-你的老张API密钥",
      "apiBaseUrl": "https://api2.laozhang.ai",
      "hasCompletedOnboarding": true
    }
    ```

    该配置适合需要项目级固定配置的场景。全局配置仍建议放在 `~/.claude/settings.json`。
  </Accordion>

  <Accordion title="API Key 无效或分组错误">
    确保使用的是老张API密钥，并且令牌创建时选择了「Claude Code」分组。可以在 [老张API控制台](https://api2.laozhang.ai/token) 重新生成令牌后再测试。
  </Accordion>

  <Accordion title="如何更新 Claude Code">
    运行以下命令更新到最新版本：

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

    更新后重新打开终端，再运行 `claude`。
  </Accordion>
</AccordionGroup>

## 最佳实践

| 建议              | 说明                                         |
| --------------- | ------------------------------------------ |
| 默认使用 Sonnet 4.6 | 成本和质量更平衡，适合大多数日常开发                         |
| 复杂任务切换 Opus 4.7 | 架构调整、跨文件重构和长流程任务更适合 Opus                   |
| 大修改先要计划         | 先让 Claude Code 输出修改计划，再执行文件改动              |
| 保留 Git 检查       | 修改前后使用 `git status`、`git diff` 和项目测试命令确认结果 |
| 价格看控制台          | Claude Code 按 Token 使用量计费，具体价格以控制台实时展示为准   |

## 相关资源

<CardGroup cols={2}>
  <Card title="官方文档" icon="book" href="https://docs.anthropic.com/zh-CN/docs/claude-code/setup">
    Claude Code 官方文档
  </Card>

  <Card title="老张API控制台" icon="cog" href="https://api2.laozhang.ai/token">
    管理 API 密钥
  </Card>

  <Card title="模型介绍" icon="bot" href="/api-capabilities/model-info">
    查看当前 Claude 系列模型
  </Card>

  <Card title="Cline 配置" icon="code" href="/scenarios/programming/cline">
    VS Code 中的 AI Agent
  </Card>
</CardGroup>

需要更多帮助？请访问 [老张API官网](https://api2.laozhang.ai) 获取支持。