# Claude Code 集成

Claude Code 是 Anthropic 推出的 AI 编程助手。TokenFlows 可通过 Claude 协议适配层在 Claude Code 终端或 IDE 插件中调用 Claude 与 GPT 系列模型。

## 前置条件

- **Node.js 环境**：Claude Code 依赖 Node.js，建议安装 Node.js 18+。
- **Claude Code**：如未安装，可执行 `npm install -g @anthropic-ai/claude-code`。
- **API Key**：在 [TokenFlows 控制台](https://dash.tokenflows.org/) 创建一个 API Key。

## 配置地址易错点

Claude Code 会自动拼接请求路径，`ANTHROPIC_BASE_URL` 只需要填写网关根地址。

正确写法：

```bash
ANTHROPIC_BASE_URL=https://api.tokenflows.org
```

不要这样写：

```bash
ANTHROPIC_BASE_URL=https://api.tokenflows.org/v1
```

地址末尾加 `/v1` 会导致 Claude Code 拼出的请求路径不正确，从而出现连接失败或 404。

## 可用 GPT 适配模型

TokenFlows 将部分 GPT 模型映射为 Claude Code 可直接调用的模型名：

| Claude Code 模型名 | 说明 |
| --- | --- |
| `cc-gpt-5.5` | 新一代 GPT 模型映射，兼容性仍在优化中，多轮对话如遇报错建议先切换到 `cc-gpt-5.4` |
| `cc-gpt-5.4` | 推荐优先使用，适合大多数 Claude Code 场景 |
| `cc-gpt-5.2` | 可作为兼容或成本控制选项 |

这些模型通过协议适配层将 GPT 响应转换为 Claude Code 可识别的格式，无需在 Claude Code 侧安装额外插件。

## 方式一：CC Switch 可视化配置（推荐）

使用 [CC Switch](https://github.com/farion1231/cc-switch/releases) 可以避免手动编辑配置文件。

1. 下载并安装 [CC Switch](https://github.com/farion1231/cc-switch/releases)。
2. 打开 CC Switch，选择 `Claude Code`。
3. 新增 TokenFlows Provider：
   - API Base URL：`https://api.tokenflows.org`
   - API Key：填入你的 TokenFlows API Key
   - Model：建议填写 `cc-gpt-5.4`
4. 启用该 Provider。
5. 在项目目录运行 `claude`。

如需切换模型分组，在 TokenFlows 控制台创建新密钥后，通过 CC Switch 更新 Provider 即可。

## 方式二：手动配置 settings.json

Claude Code 可通过 `~/.claude/settings.json` 中的 `env` 字段读取网关配置。

配置文件位置：

- macOS / Linux：`~/.claude/settings.json`
- Windows：`C:\Users\你的用户名\.claude\settings.json`

写入或合并以下配置：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.tokenflows.org",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "cc-gpt-5.4",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "cc-gpt-5.4",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "cc-gpt-5.4",
    "ANTHROPIC_MODEL": "cc-gpt-5.4"
  }
}
```

将 `YOUR_API_KEY` 替换为你的 TokenFlows API Key。多个模型字段统一设置为 `cc-gpt-5.4`，可以避免 Claude Code 在不同调用路径中自动切换到未配置模型。

配置完成后，退出并重新启动 Claude Code：

```bash
claude
```

## 方式三：临时环境变量

如果只想在当前终端会话中测试，可以临时设置环境变量：

```bash
# macOS / Linux
export ANTHROPIC_BASE_URL="https://api.tokenflows.org"
export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"
export ANTHROPIC_MODEL="cc-gpt-5.4"
claude
```

```powershell
# Windows PowerShell
$env:ANTHROPIC_BASE_URL = "https://api.tokenflows.org"
$env:ANTHROPIC_AUTH_TOKEN = "YOUR_API_KEY"
$env:ANTHROPIC_MODEL = "cc-gpt-5.4"
claude
```

## 推理深度配置

Claude Code 支持通过 `--effort` 指定推理深度。深度越高，复杂任务效果通常越好，但 token 消耗也会增加。

```bash
claude --effort low
claude --effort medium
claude --effort high
```

也可以同时指定模型：

```bash
claude --model cc-gpt-5.4 --effort medium
```

如需持久化默认推理深度，可在 `settings.json` 中加入 `output_config`：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.tokenflows.org",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "ANTHROPIC_MODEL": "cc-gpt-5.4"
  },
  "output_config": {
    "effort": "high"
  }
}
```

| effort | 适用场景 | Token 消耗 |
| --- | --- | --- |
| `low` | 简单问答、快速补全 | 少 |
| `medium` | 常规开发任务 | 中 |
| `high` | 复杂推理、架构设计 | 多 |

命令行中的 `--effort` 会临时覆盖 `settings.json` 中的默认值。

## 常见问题

**Q：连接失败或返回 404？**

检查 `ANTHROPIC_BASE_URL` 是否为 `https://api.tokenflows.org`，末尾不要加 `/v1`。

**Q：返回 401 或鉴权失败？**

确认 `ANTHROPIC_AUTH_TOKEN` 已填入完整 API Key，并检查密钥是否有效、账号是否可正常使用。

**Q：多轮对话后模型报错？**

如果正在使用 `cc-gpt-5.5`，建议先切换到兼容性更稳定的 `cc-gpt-5.4`。

**Q：为什么要同时设置多个 `ANTHROPIC_DEFAULT_*_MODEL`？**

Claude Code 在不同模式或调用路径下可能读取不同默认模型字段。统一设置可以减少模型自动切换导致的请求失败。