Claude Code 中转站安装与配置教程

# Claude Code 中转站安装与配置教程

> 适用对象：Anthropic 官方终端编程助手 Claude Code  
> 中转站地址：`https://api.zaimod.com`  
> 结构：准备 → 安装 → 取令牌 → 写配置 → 启动 → 验证 → 排错，赶时间可直接跳 **五、配置速查表**

---

## 一、开始之前

### 1.1 准备清单

| 项目                     | 应该填什么                   | 说明                          |
| ---------------------- | ----------------------- | --------------------------- |
| `ANTHROPIC_BASE_URL`   | `https://api.zaimod.com` | **只写到域名**，不带 `/v1`，末尾不加 `/` |
| `ANTHROPIC_AUTH_TOKEN` | `sk-` 开头的令牌             | 在中转站控制台「API 令牌」页新建          |
| 模型名                    | 如 `claude-opus-4-6`     | 以控制台模型列表里的实际 ID 为准          |
| Node.js                | ≥ 18（新版安装器自带运行时，可跳过）    | `node -v` 检查                |

### 1.2 三个必须先搞清楚的点

**① BASE_URL 不能带 `/v1`**

Claude Code 请求时会自己拼 `/v1/messages`。你写 `https://api.zaimod.com/v1`，实际请求就成了 `/v1/v1/messages` —— 这个路径在中转站上实测返回 `404 Invalid URL`。

**② 令牌分组必须支持工具调用**

Claude Code 全程依赖工具调用（读写文件、执行命令）。原文这条提醒非常重要，保留并解释清楚：

- ✅ 可选：名字里带 **Claude Code 专属**、**特价 Claude Code**、**官转克劳德** 等字样的分组
- ❌ 不要选 `default` 分组，也不要选标着「逆向」的分组 —— 这两类不支持工具调用，接上后会表现为「能聊天但不会改文件」

**③ 用 `ANTHROPIC_AUTH_TOKEN`，不要用 `ANTHROPIC_API_KEY`**

中转站认的是 `Authorization: Bearer sk-...`，对应 `ANTHROPIC_AUTH_TOKEN`。如果系统环境里还残留 `ANTHROPIC_API_KEY`，Claude Code 可能优先走官方登录流程，导致配置不生效。建议先执行 `unset ANTHROPIC_API_KEY`（Windows：`set ANTHROPIC_API_KEY=` 清空）再启动。

---

## 二、安装

### 步骤 1 · 检查 Node.js（可跳过）

```bash
node --version
```

返回 `v18.x` 及以上即满足要求。新版官方安装器自带运行时，若你用的是步骤 2 的 curl / winget 方式，这一步可以不装。

需要装的话：

```bash
# Ubuntu / Debian
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo bash -
sudo apt-get install -y nodejs

# macOS（先装 Xcode 命令行工具与 Homebrew）
xcode-select --install
brew install node
```

### 步骤 2 · 安装 Claude Code

四种方式任选其一，官方推荐第一种。

```bash
# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash
```

```powershell
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
```

```bash
# macOS 用 Homebrew
brew install --cask claude-code
```

```powershell
# Windows 用 winget
winget install Anthropic.ClaudeCode
```

装完如果提示找不到命令，把安装目录加进 PATH（原文给了这条，但只给了 bash 版本）：

```bash
# macOS / Linux / WSL：写入 shell 配置
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
# zsh 用户把 ~/.bashrc 换成 ~/.zshrc
```

Windows 一般由安装器自动写入 PATH，**需重开一个终端**才生效。

### 步骤 3 · 验证安装

```bash
claude --version
```

能打印版本号即可。此时**先别启动**，先去配好配置，否则首次启动会引导你走官方账号登录。

---

## 三、获取令牌

进入中转站控制台 → 「API 令牌」→「添加令牌」：

| 选项 | 建议值                                                                      |
| -- | ------------------------------------------------------------------------ |
| 名称 | 随意，建议写 `claude-code` 便于日后识别                                              |
| 额度 | 设为无限额度（或按需限额）                                                            |
| 分组 | 选带 **Claude Code 专属 / 特价 Claude Code / 官转克劳德** 字样的分组；**不要 default、不要逆向** |
| 其他 | 保持默认                                                                     |

创建后复制那串 `sk-` 开头的字符备用。

---

## 四、写配置文件

### 步骤 4 · 创建 `~/.claude/settings.json`

全局配置文件路径：

| 系统                  | 路径                                       |
| ------------------- | ---------------------------------------- |
| macOS / Linux / WSL | `~/.claude/settings.json`                |
| Windows             | `C:\Users\<你的用户名>\.claude\settings.json` |

**macOS / Linux / WSL（heredoc 一次写入）**

```bash
# 先确保目录存在，否则重定向会报 No such file or directory
mkdir -p ~/.claude

cat > ~/.claude/settings.json <<'EOF'
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.zaimod.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的令牌",
    "ANTHROPIC_MODEL": "claude-opus-4-6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-opus-4-6",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-opus-4-6",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6",
    "API_TIMEOUT_MS": "300000",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}
EOF
```

**Windows（手动创建最稳）**

```powershell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude" | Out-Null
notepad "$env:USERPROFILE\.claude\settings.json"
```

在打开的记事本里粘贴上面那段 JSON（**不含 `#` 注释**），保存时注意文件名是 `settings.json`，别存成 `settings.json.txt`。

### 字段说明

| 字段                                       | 作用                                                 |
| ---------------------------------------- | -------------------------------------------------- |
| `ANTHROPIC_BASE_URL`                     | 中转站地址，纯域名                                          |
| `ANTHROPIC_AUTH_TOKEN`                   | 你的 `sk-` 令牌                                        |
| `ANTHROPIC_MODEL`                        | 交互主模型，日常对话与写代码都用它                                  |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL`          | Explore 子代理、对话摘要等后台轻量任务                            |
| `ANTHROPIC_DEFAULT_SONNET_MODEL`         | `opusplan` 模式的执行阶段                                 |
| `ANTHROPIC_DEFAULT_OPUS_MODEL`           | `opusplan` 模式的规划阶段                                 |
| `API_TIMEOUT_MS`                         | 请求超时，300000 = 5 分钟。中转站偶有排队，调大更稳                    |
| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | `"1"` 表示不再向接口发送实验性 beta 头。中转站通常不支持这些头，关掉可减少 400 报错 |

> 原文把四个模型字段全填成同一个模型，是因为不少中转站只有一个 Claude 型号。若你的平台同时提供 haiku / sonnet / opus，建议分开填，后台轻量任务走 haiku 更省钱。

### 步骤 5 · 校验配置文件是合法 JSON

这一步原文没有，但它能拦下绝大多数「配置写了却报错」的问题：

```bash
python3 -m json.tool ~/.claude/settings.json
```

```powershell
# 没有 python 就用 PowerShell
Get-Content "$env:USERPROFILE\.claude\settings.json" -Raw | ConvertFrom-Json
```

**能原样打印出来 = 合法**；报 `Expecting property name` 之类 = JSON 里有注释、多余逗号或多写了括号。

### 步骤 6 · 首次运行引导

```bash
claude
```

依次四步，全部按 Enter 即可：

1. **选择主题** → 选一个喜欢的
2. **安全须知** → 确认
3. **Terminal 配置** → 用默认
4. **工作目录信任** → 信任当前目录

> 如果这里出现的是「登录 Claude 账号 / 输入 API Key」的引导页，说明 `settings.json` 没被读到：检查文件路径、文件名后缀、以及 JSON 是否合法。

### 步骤 7 · 验证是否真的走了中转

**非交互快速验证：**

```bash
claude -p "用一句话说明你是谁"
```

**确认链路：**

- 有正常回复 **且** 中转站控制台「调用日志」里出现这次请求 → 配置成功。
- 有回复但控制台无任何记录 → 仍在走官方，回头检查 `ANTHROPIC_BASE_URL` 是否被系统环境变量覆盖。
- 报 `Invalid API Key · Please run /login` → 见下一节第一条。

---

## 五、配置速查表

| 配置项                    | 值                                                                        |
| ---------------------- | ------------------------------------------------------------------------ |
| `ANTHROPIC_BASE_URL`   | `https://api.zaimod.com`（不带 `/v1`）                                        |
| `ANTHROPIC_AUTH_TOKEN` | `sk-...`                                                                 |
| 模型                     | `claude-opus-4-6`（按平台实际 ID 调整）                                           |
| 配置文件                   | `~/.claude/settings.json`（Windows：`%USERPROFILE%\.claude\settings.json`） |
| 令牌分组                   | Claude Code 专属 / 特价 Claude Code / 官转克劳德；**避开 default 与逆向**               |
| 超时                     | `API_TIMEOUT_MS: "300000"`                                               |
| 启动命令                   | `claude`；单次问答 `claude -p "..."`                                          |

---

## 六、常见问题

| 现象                                    | 原因                                                      | 处理                                                       |
| ------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------- |
| `Invalid API Key · Please run /login` | 没读到配置，或环境变量被覆盖                                          | 确认 `settings.json` 路径与文件名；`unset ANTHROPIC_API_KEY`；重启终端 |
| 能聊天但不会改文件、不执行命令                       | 令牌分组不支持工具调用                                             | 换 Claude Code 专属 / 官转类分组，避开 `default` 与逆向分组              |
| `404 Invalid URL`                     | `ANTHROPIC_BASE_URL` 带了 `/v1`，变成 `/v1/v1/messages`      | 改成纯域名                                                    |
| `401` / `Invalid token`               | 令牌错、已删除、额度耗尽                                            | 控制台重建令牌，确认前缀 `sk-`                                       |
| JSON 报错、Claude 启动即退出                  | `settings.json` 里写了 `#` 注释或多了逗号                         | 用步骤 5 的命令校验，删掉全部注释                                       |
| 显示 `offline`                          | Claude Code 以能否连上 Google 判断网络状态                         | **不影响使用**，可忽略                                            |
| 网页 Fetch 失败                           | 访问网页前会先调 Claude 服务做安全校验                                 | 需要稳定的国际网络，必要时全局代理                                        |
| `fetch failed` / 请求超时                 | 网络或中转站排队                                                | 先 `Ctrl+C` 退出重开 `claude`；仍失败则调大 `API_TIMEOUT_MS`         |
| 日志里偶发 `count_tokens` 404              | 中转站未实现该辅助接口（实测 `POST /v1/messages/count_tokens` 返回 404） | 属正常现象，只影响本地 token 预估显示，不影响对话与工具调用                        |

---

## 附录 A · 原文勘误

这篇原文的主要问题不在文字量，而在**配置示例根本不能直接用**：

1. **`settings.json` 示例是非法 JSON**：里面夹了大量 `# 您的api令牌`、`# 交互主模型` 这类注释。JSON 不支持注释，照抄过去 Claude Code 会解析失败、配置完全不生效。本文已改为纯 JSON，字段含义移到独立表格。
2. **heredoc 里混入了操作说明**：`cat > ... << 'EOF'` 的正文中写着「第二步 替换令牌…」「第三步 输入以下命令」，这些是**操作指引**而不是文件内容。真按原文执行，它们会被原样写进 `settings.json`，文件立刻损坏。
3. **同一份配置贴了两遍**：先是「完整 settings.json 配置文件展示」，紧接着 heredoc 里又完整重复一次，两处缩进还不一样。
4. **标题与内容不符**：小标题写「使用 npm 全局安装 Claude Code」，下面的内容却是 curl / PowerShell / Homebrew / winget 四种官方安装器，**一条 npm 命令都没有**。
5. **漏了 `mkdir -p ~/.claude`**：`~/.claude` 目录在首次使用前并不存在，直接重定向会报 `No such file or directory`。
6. **只给了 bash 的 PATH 写法**：Windows 用户遇到 `claude 不是内部或外部命令` 时无解，已补充说明。
7. **没给 Windows 的配置路径**：全文只写 `~/.claude/settings.json`，Windows 用户不知道对应 `%USERPROFILE%\.claude\settings.json`。
8. **没有校验环节**：写完配置直接启动，出错也无法定位。已补步骤 5 的 JSON 校验与步骤 7 的双重验证。
9. **系统要求写 Windows (WSL)**：官方已支持原生 Windows（PowerShell 脚本与 winget 安装），已按现状更新。
10. **「主站地址url」占位符**：原文配置里写的是「主站地址url」字样，不是可填的值。已统一替换为 `https://api.zaimod.com`。

---

## 附录 B · 地址变更对照

| 位置                                     | 原值             | 现值                      |
| -------------------------------------- | -------------- | ----------------------- |
| `settings.json` → `ANTHROPIC_BASE_URL` | `主站地址url`（占位符） | `https://api.zaimod.com` |
| 控制台入口                                  | 原主站域名          | `https://api.zaimod.com` |

> **迁移提醒**：旧平台的令牌不能沿用，需在新平台重新生成；且新令牌必须选择支持工具调用的分组，否则 Claude Code 只能聊天、无法改文件。

上一篇：Gemini CLI 中转站配置教程{else}上一篇：没有了下一篇：Cherry Studio接入中转站调用MCP{else}下一篇：没有了