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

# Claude Code 接入 XRouter

> 在 Claude Code 中配置 XRouter API Key、Anthropic Messages 兼容地址和默认模型。

Claude Code 使用 Anthropic Messages API 格式。接入 XRouter 时，把 Claude Code 的 Anthropic 服务地址指向 XRouter，并使用 XRouter API Key 作为认证凭据。

<Warning>
  XRouter API Key 属于敏感凭据。建议写入本机 shell 配置、终端环境变量或密钥管理工具，不要写入项目仓库。
</Warning>

## 前置条件

* 已安装 Claude Code。
* 已在 XRouter 控制台创建 API Key，格式通常为 `sk-...`。
* 已从控制台模型页复制可用的 Claude 模型 ID。

## 安装 Claude Code

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

安装完成后确认命令可用：

```bash Terminal theme={null}
claude --version
```

## 配置 XRouter

把以下环境变量加入你的 shell 配置文件，例如 `~/.zshrc`、`~/.bashrc` 或 CI 的 secret 配置。

```bash ~/.zshrc theme={null}
export ANTHROPIC_BASE_URL="https://api.xrouter.dev"
export ANTHROPIC_AUTH_TOKEN="sk-your-api-key"
export ANTHROPIC_MODEL="your-claude-model-id"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="your-fast-claude-model-id"
```

重新加载配置：

```bash Terminal theme={null}
source ~/.zshrc
```

| 变量                              | 说明                               |
| ------------------------------- | -------------------------------- |
| `ANTHROPIC_BASE_URL`            | XRouter 服务根地址，不追加 `/v1/messages` |
| `ANTHROPIC_AUTH_TOKEN`          | XRouter API Key                  |
| `ANTHROPIC_MODEL`               | Claude Code 主模型，从控制台复制           |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | 可选，Claude Code 用于轻量任务的模型，从控制台复制  |

<Info>
  如果控制台显示了不同 `server_address`，请把 `ANTHROPIC_BASE_URL` 替换成控制台地址。Claude Code 会自行拼接 `/v1/messages`。
</Info>

<Note>
  旧教程中可能出现 `ANTHROPIC_SMALL_FAST_MODEL`。新配置建议使用 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。
</Note>

## 启动并验证

进入一个代码仓库后启动 Claude Code：

```bash Terminal theme={null}
cd path/to/your-project
claude
```

你可以先让 Claude Code 执行只读任务：

```text Prompt theme={null}
请阅读当前项目结构，并总结这个仓库的主要模块。不要修改文件。
```

如果工具能正常返回结果，说明 XRouter 接入已经完成。

## 临时会话配置

如果你只想在当前终端会话中启用 XRouter，不写入 shell 配置，可以这样启动：

```bash Terminal theme={null}
ANTHROPIC_BASE_URL="https://api.xrouter.dev" \
ANTHROPIC_AUTH_TOKEN="sk-your-api-key" \
ANTHROPIC_MODEL="your-claude-model-id" \
claude
```

## 故障排查

<AccordionGroup>
  <Accordion title="Claude Code 报 401">
    确认 `ANTHROPIC_AUTH_TOKEN` 是完整 XRouter API Key。也可以用 `curl https://api.xrouter.dev/v1/models -H "x-api-key: sk-your-api-key" -H "anthropic-version: 2023-06-01"` 验证 Anthropic 格式认证。
  </Accordion>

  <Accordion title="模型名不可用">
    在 XRouter 控制台复制 Claude 模型 ID，并同步修改 `ANTHROPIC_MODEL`。不同 Key、模型限制或账户状态可能影响可用模型。
  </Accordion>

  <Accordion title="连接地址写了但仍然请求失败">
    确认 `ANTHROPIC_BASE_URL` 是服务根地址，例如 `https://api.xrouter.dev`，不要写成 `https://api.xrouter.dev/v1/messages`。
  </Accordion>

  <Accordion title="代理或公司网络拦截">
    先用 `curl https://api.xrouter.dev/v1/models -H "Authorization: Bearer sk-your-api-key"` 验证网络连通性。若公司网络要求代理，请按你的终端环境配置 `HTTPS_PROXY`。
  </Accordion>
</AccordionGroup>