Claude Code CLI 与 VS Code 插件 · 中转站配置教程

# Claude Code CLI 与 VS Code 插件 · 中转站配置教程

> 适用：Claude Code CLI（Windows / macOS / Linux）、VS Code 里的 Claude Code 插件  
> 中转站地址：`https://api.zaimod.com`  
> 主线：**建令牌 → 装 CLI → 写 `~/.claude/settings.json` 两行 → 启动验证**，全程约 10 分钟

---

## 一、先确认你该看哪一段

Claude Code 有三个入口，配置方式不同，**别混着装**：

| 入口                                 | 要不要装 Node.js         | 配置写在哪                     | 本文对应章节 |
| ---------------------------------- | -------------------- | ------------------------- | ------ |
| **Claude Code CLI**（终端里敲 `claude`） | 用 npm 装才需要（Node 22+） | `~/.claude/settings.json` | 第三～六章  |
| **VS Code 插件**                     | **不需要**              | 同上，插件读同一份文件               | 第七章    |
| **桌面版（Desktop App）**               | 不需要                  | 桌面版有自己的设置页                | 不在本文范围 |

三个入口共用同一个配置目录 `~/.claude`，所以**配置只需写一次**，CLI 和插件会同时生效。这也是很多人误以为"插件要另外配一遍"的原因。

---

## 二、一分钟速查表

急着用的人只看这张表，具体步骤跳到对应章节。

| 项目                     | 填什么                                                                                    |
| ---------------------- | -------------------------------------------------------------------------------------- |
| `ANTHROPIC_BASE_URL`   | `https://api.zaimod.com` —— **只到域名，不带 `/v1`，不带 `/v1/messages`，末尾不加 `/`**                |
| `ANTHROPIC_AUTH_TOKEN` | 控制台「令牌管理」复制出的完整密钥                                                                      |
| 配置文件                   | macOS / Linux：`~/.claude/settings.json`；Windows：`C:\Users\<用户名>\.claude\settings.json` |
| 令牌分组                   | **Claude Code 全球高防**（限 CC 内使用）                                                         |
| 模型可用列表                 | **留空**                                                                                 |
| 验证命令                   | `claude --version` → `claude` → 发一句"你好"                                                |

---

## 三、第一步：先建令牌（三系统通用）

配置里要填的那串密钥，得先去控制台拿。

**1. 打开控制台 → 左侧「令牌管理」→ 创建令牌**

**2. 名称**随便写，建议 `claude`，日后好认。

**3. 智能路由「可选择智能自动」**

![](/uploads/editor/20261101/img_6ae62266241615.66832925.png)

这个分组在列表里标注的是 **1.8x 倍率**、**限客户端满血 MAX 号池、仅在 CC 内使用**。倍率高意味着同样的问题消耗的额度更多，但它对应的正是 Claude Code 需要的满血号池 + 工具调用能力 —— 换便宜分组省下的钱，通常会以"能聊天但不会改文件"的形式还回来。

**4. 模型可用列表：留空**

原文这条提醒值得单独拎出来说：填写后，只要列表里不包含当前使用的模型，请求就会返回 **403**。Claude Code 会自己挑模型、还会调子代理用轻量模型，你很难把列表填全，所以直接留空最省事。

**5. 提交 → 回到令牌列表 → 在「密钥」列复制**

![](/uploads/editor/20261101/img_6ae6228fec6b91.77899213.png)

密钥列右侧有个复制菜单，选「复制密钥」拿到的就是**密钥本身**；「复制连接信息」拿到的是带 `Base URL` 和 `Bearer` 前缀的一整段，那个不能直接粘进 `settings.json`。

> 复制后先存到记事本里备用，下一步要用。

---

## 四、Windows

### 4.1 安装 CLI

按下 `Win + R`，输入 `powershell` 回车，在 PowerShell 里执行**下面两条中的一条**。

**推荐：官方原生安装器**（不依赖 Node.js，自带运行时，后台自动更新）

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

**备选：npm**（需要 Node.js 22 以上）

```powershell
npm install -g @anthropic-ai/claude-code
```

![](/uploads/editor/20261101/img_6ae622a0158b67.79377423.png)

输出 `added 2 packages in 1m` 就算装完 —— 只有 2 个包，说明这个 npm 包现在只是个薄壳，真正装的还是那个原生二进制。后面那几行 `npm notice New major version of npm available` 是提示 npm 自己有新版本，与 Claude Code 无关，可以不管。

```text
原文只给了这一条 npm 命令。npm 安装方式自 2026 年 1 月起已被官方标记为弃用，
且这个包现在要求 Node.js 22+。能用安装器就别用 npm。
```

### 4.2 验证安装

```powershell
claude --version
```

![](/uploads/editor/20261101/img_6ae622abc0d4c4.31276096.png)

能打印出版本号就说明装好了。**此时先别急着敲 `claude`** —— 配置还没写，首次启动会把你带进官方账号登录引导。先把 4.3 做完。

### 4.3 写 `settings.json`

Claude Code 的配置目录是 `$HOME\.claude`，通常就是 `C:\Users\你的用户名\.claude`。不用手动去资源管理器里翻，直接执行：

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

第一行确保目录存在（不存在时记事本保存会失败），第二行会打开 `settings.json`；文件不存在时，记事本会在保存那一刻把它创建出来。

![](/uploads/editor/20261101/img_6ae622bb000907.89036463.png)

在打开的记事本里**清空原有内容**，粘贴下面这段，然后保存：

```json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "你的API_KEY",
    "ANTHROPIC_BASE_URL": "https://api.zaimod.com"
  },
  "includeCoAuthoredBy": false
}
```

把 `你的API_KEY` 这七个字整个选中（连引号里的内容一起），替换成上一步复制的密钥。**只替换这一段，别把引号删掉。**

两个必须注意的保存细节：

- 文件名必须是 `settings.json`。记事本默认会存成 `settings.json.txt`，保存对话框里把「保存类型」改成「所有文件」再存。
- 编码选 **UTF-8**。Windows 记事本现在默认就是 UTF-8，但如果你是从别处复制过来的文件，注意别存成 UTF-8 with BOM —— BOM 会让 JSON 解析直接失败。

### 4.4 校验 JSON 是否合法

这一步原文没有，但它能拦下绝大多数"配置写了却不生效"的情况：

```powershell
Get-Content "$HOME\.claude\settings.json" -Raw | ConvertFrom-Json
```

能原样打印出来 = 合法；报 `ConvertFrom-Json : Invalid JSON primitive` = 里面有中文引号、多余逗号或少了括号。

### 4.5 启动

```powershell
claude
```

判断标准见第九章。

---

## 五、macOS

### 5.1 安装 CLI

`Command + Space` 打开聚焦搜索，输入「终端」或 `Terminal` 回车。下面所有命令都在这一个窗口里执行。

**推荐：官方原生安装器**

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

**备选一：Homebrew**（不会自动更新，需要手动 `brew upgrade claude-code`）

```bash
brew install --cask claude-code
```

**备选二：npm**（需要 Node.js 22+，已弃用）

```bash
npm install -g @anthropic-ai/claude-code
```

> 原文这里写了"如果权限不足就加 `sudo`"。**不要加 `sudo` 装 npm 全局包** —— 官方明确警告过，它会把文件写进 root 拥有的目录，后续 `npm update` 全部报 EACCES，还带安全隐患。真遇到 EACCES，改用原生安装器，或者用 nvm 管理 Node。

### 5.2 补 PATH

原生安装器把二进制放在 `~/.local/bin`。如果 `claude --version` 报 `command not found`：

```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
```

macOS 现在默认是 zsh；如果你用的是 bash，把 `~/.zshrc` 换成 `~/.bashrc`。

### 5.3 写 `settings.json`

配置目录是 `~/.claude`。三条命令：建目录 → 建空文件 → 用「文本编辑」打开。

```bash
mkdir -p ~/.claude
touch ~/.claude/settings.json
open -e ~/.claude/settings.json
```

![](/uploads/editor/20261101/img_6ae622e8dd6819.64624793.png)

上图是「访达 → 前往 → 前往文件夹」（`Shift + Command + G`）输入 `~/.claude` 后的效果，可以用它确认文件确实建出来了：`.claude` 是目录，`.claude.json`、`.claude.json.backup` 是 Claude Code 自己维护的登录态与备份。

清空内容，粘贴同一份 JSON（把 `你的API_KEY` 换成真实密钥）：

```json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "你的API_KEY",
    "ANTHROPIC_BASE_URL": "https://api.zaimod.com"
  },
  "includeCoAuthoredBy": false
}
```

`Command + S` 保存。文本编辑如果提示"无法存储，文件已被其他程序修改"，选「仍要存储」。

### 5.4 校验 JSON

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

没有 python3 就用 `jq . ~/.claude/settings.json`（没装 jq 的话 `brew install jq`）。

### 5.5 启动

```bash
claude
```

---

## 六、Linux

### 6.1 安装 CLI

```bash
# 推荐：原生安装器
curl -fsSL https://claude.ai/install.sh | bash

# 备选：npm（Node 22+，已弃用）
npm install -g @anthropic-ai/claude-code
```

`~/.local/bin` 不在 PATH 时：

```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
```

Alpine 之类的精简发行版还要补依赖：

```bash
apk add libgcc libstdc++ ripgrep
```

### 6.2 写 `settings.json`

```bash
mkdir -p ~/.claude
nano ~/.claude/settings.json
```

粘贴同一份 JSON，然后按 **`Ctrl + O` → 回车确认文件名 → `Ctrl + X`** 退出。

```json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "你的API_KEY",
    "ANTHROPIC_BASE_URL": "https://api.zaimod.com"
  },
  "includeCoAuthoredBy": false
}
```

> nano 直接 `Ctrl + V` 粘贴有时会因为终端不支持 bracketed paste 而丢字符。粘完往上翻一眼，确认大括号和引号都在。

### 6.3 校验 JSON

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

### 6.4 启动

```bash
claude
```

---

## 七、VS Code 插件

插件和 CLI **共用同一份 `~/.claude/settings.json`**，所以只要第四章～第六章任意一段做过，这里不用再配第二遍。

**步骤：**

1. VS Code 扩展市场搜 `Claude Code`，装 Anthropic 官方那个（发布者 `Anthropic`）。
2. 装完左侧活动栏会出现 Claude 图标。**先打开一个项目文件夹**（`文件 → 打开文件夹`），别在空窗口里用。
3. 点开 Claude 面板，输入框里发一句：

```text
你好
```

![](/uploads/editor/20261101/img_6ae62307bb1ed4.24277519.png)

1. 正常返回内容 = 配置成功。

**装完插件仍提示登录 / 401**，基本都是同一个原因：插件读的是 `C:\Users\<用户名>\.claude\settings.json`（或 `~/.claude/settings.json`），而不是项目里的 `.claude/settings.json`。项目级配置只放权限和 hooks，凭证必须放在用户级那份里。

---

## 八、配置项逐条解释

| 字段                         | 作用                                              | 备注                                                                                          |
| -------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `env.ANTHROPIC_BASE_URL`   | 请求发往哪里                                          | **纯域名**。Claude Code 自己会拼 `/v1/messages`，写成 `https://api.zaimod.com/v1` 就变成 `/v1/v1/messages` |
| `env.ANTHROPIC_AUTH_TOKEN` | 身份凭证                                            | 中转站认的是 `Authorization: Bearer <key>`，对应的就是这个字段                                              |
| `includeCoAuthoredBy`      | 是否在 git commit / PR 里加 `Co-Authored-By: Claude` | `false` = 不加。**该字段自 v2.0.62 起已弃用**，官方推荐改用 `attribution`                                     |

关于第三条，原文用的写法还能生效（Claude Code 仍兼容旧字段），但新版本更推荐：

```json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "你的API_KEY",
    "ANTHROPIC_BASE_URL": "https://api.zaimod.com"
  },
  "attribution": {
    "commit": "",
    "pr": ""
  }
}
```

`attribution` 粒度更细：`commit` 控制提交里的 trailer，`pr` 控制 PR 描述里的那行，另有 `sessionUrl` 控制云会话链接。三个都清空就等于完全不留痕。注意 `attribution: false` 这种简写要 v2.1.281 以上才认，旧版本遇到会**跳过整份配置文件**，所以别图省事写布尔值。

### 可选：固定模型

原文没写，但很多人配完会问"到底在用哪个模型"。想锁定，就在 `env` 里补一行（模型 ID 以控制台模型列表为准），完整写法：

```json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "你的API_KEY",
    "ANTHROPIC_BASE_URL": "https://api.zaimod.com",
    "ANTHROPIC_MODEL": "claude-opus-4-6"
  }
}
```

不写也能用 —— Claude Code 会走服务端默认模型，启动画面左下角会显示它最终选中的是哪个。

---

## 九、怎么算配置成功

按顺序看三个信号，全都对上才算真的接上了中转站。

**① 版本号正常**

```bash
claude --version
```

**② 进入界面，且左下角写的是「API Usage Billing」**

```bash
claude
```

![](/uploads/editor/20261101/img_6ae62327afef91.97736842.png)

欢迎屏幕左下角那行 `Opus 4.6 · API Usage Billing` 是判断关键：

- 显示 **API Usage Billing** → 走的是 API Key 计费，也就是你的中转站余额 ✅
- 显示 **Claude Pro / Max** → 你登录的是官方订阅，配置没生效 ❌

顺便说一句：截图里启动路径是 `/Users/dvd`（家目录），界面因此提示 "You have launched claude in your home directory"。**养成先 `cd` 到项目目录再敲 `claude` 的习惯**，在家目录启动它会把整个用户目录当工作区扫，又慢又容易误改文件。

**③ 发一句话，去控制台对账**

```text
你好
```

有回复 ≠ 走通了。真正可靠的证据是**控制台「使用日志」里出现这次调用记录**：

- 有回复 + 日志有记录 → 完全打通
- 有回复 + 日志空 → 还在走官方，回头查 `ANTHROPIC_BASE_URL` 是否被系统环境变量覆盖
- 无回复 + 日志空 → 看第十章

**脚本/CI 里的非交互验证：**

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

---

## 十、常见问题

| 现象                                                  | 原因                                                                                            | 处理                                                                        |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `claude : 无法将"claude"项识别为...` / `command not found` | 安装目录不在 PATH，或装了没重开终端                                                                          | 重开终端；macOS/Linux 补 `~/.local/bin`；Windows 重开 PowerShell                   |
| `Invalid API Key · Please run /login`               | 没读到 `settings.json`，或文件名存成了 `.txt`                                                            | 确认路径与后缀；用 4.4 / 5.4 / 6.3 的命令校验 JSON                                      |
| 启动直接进官方登录引导                                         | 配置写在启动之后，或文件被忽略                                                                               | 退出 → 检查配置 → 重新 `claude`；顺便清掉 `ANTHROPIC_API_KEY` 环境变量（见下条）                |
| 明明配了 token，还是走官方                                    | 系统里残留 `ANTHROPIC_API_KEY`，优先级压过了 `settings.json`                                              | `unset ANTHROPIC_API_KEY`（Windows：`setx ANTHROPIC_API_KEY ""`）后重开终端       |
| `401` / `无效的令牌`                                     | 密钥复制不全、被删除、额度耗尽                                                                               | 回控制台「复制密钥」重取，注意别把 `Bearer ` 一起粘进去                                         |
| `403`                                               | 令牌的「模型可用列表」里没有当前模型                                                                            | 编辑令牌，把模型可用列表清空                                                            |
| `404 Invalid URL`                                   | `ANTHROPIC_BASE_URL` 带了 `/v1`                                                                 | 改成纯域名 `https://api.zaimod.com`                                             |
| 能聊天，但不会改文件、不执行命令                                    | 令牌分组不支持工具调用                                                                                   | 换「Claude Code 全球高防」这类分组，别用 `default` 或逆向分组                                |
| 启动即退出、报 JSON 解析错误                                   | 中文引号、多余逗号、BOM                                                                                 | 用 4.4 / 5.4 / 6.3 校验后删掉问题字符，重新存为 UTF-8                                    |
| `claude --version` 版本号比官网旧很多                        | 以前用 npm 装过，旧二进制还在 PATH 里抢在前面                                                                  | `which -a claude` 看顺序；`npm uninstall -g @anthropic-ai/claude-code` 后重装原生版 |
| 日志里偶发 `count_tokens` 404                            | 中转站未实现该辅助接口（实测 `POST /v1/messages/count_tokens` 返回 404，而 `/v1/messages` 返回 401，说明主接口在、辅助接口没挂） | 正常现象，只影响本地 token 预估显示，不影响对话与工具调用                                          |
| 显示 `offline`                                        | Claude Code 用能否访问 Google 判断网络状态                                                               | 不影响使用，可忽略                                                                 |
| 回复很慢或超时                                             | 中转站排队 / 长连接被网络设备掐断                                                                            | 先 `Ctrl + C` 重开；仍不行在 `env` 里加 `"API_TIMEOUT_MS": "300000"`                |

---

上一篇：Codex 配置教程{else}上一篇：没有了下一篇：Gemini CLI配置{else}下一篇：没有了