# Claude Code API 配置：Passion8、CC-Switch 与 settings.json

> 用 CC-Switch 或 settings.json 将 Claude Code 接入 Passion8，设置 Base URL、API Key 与可用模型，并排查认证和地址错误。

URL: https://docs.passion8.cc/docs/claude-code/settings
Language: zh-CN
Publisher: Passion8
Last updated: 2026-10-11

安装完成后，用 **Passion8 地址、API Key 和已开放的 Claude 模型 ID** 将 Claude Code 接入本站；本地 API Key 接入无需 Anthropic 账号或 OAuth 登录。本文提供两种方式:**推荐用 [CC-Switch](#用-cc-switch-配置推荐) 图形化配置**,或[手动配置](#手动配置)环境变量。新手建议直接用 CC-Switch。




Claude Code 的 Passion8 Base URL 是 `https://passion8.cc`,**不带** `/v1`。Token 使用 `ANTHROPIC_AUTH_TOKEN`,填你的 Passion8 API Key。




## 配置前准备

先确认本机已经能运行 Claude Code:

```bash
claude --version
```

如果还没安装,先看 [安装 Claude Code](https://docs.passion8.cc/docs/claude-code/install)。

你需要准备下面的接入信息：

| 项目 | 值 |
| --- | --- |
| Base URL | `https://passion8.cc` |
| Token 变量 | `ANTHROPIC_AUTH_TOKEN`，值为完整 Passion8 API Key |
| 模型 ID | Passion8 控制台向你的令牌开放的精确 Claude 模型 ID |

完成配置后只有一个判断标准:测试命令能正常返回内容。如果返回认证错误,先检查 Token;如果返回连接错误,先检查 Base URL 是否误写了 `/v1`。

## 用 CC-Switch 配置(推荐)

CC-Switch 用图形界面管理 Claude Code 配置,不用手写 JSON,是最省事的接入方式。macOS 和 Windows 填写字段一致。







### 安装并打开 CC-Switch

如果还没安装,先从 [CC-Switch Releases](https://github.com/farion1231/cc-switch/releases) 下载对应系统版本。打开后在应用列表里选择 `Claude Code`。






### 添加应用专属配置

添加 Claude Code 的应用专属配置,固定填写:

| 字段 | 值 |
| --- | --- |
| 名称 | `Passion8 Claude Code` |
| 端点/Base URL | `https://passion8.cc` |
| API Key | `sk-你的 Passion8 API Key` |
| 环境变量 | `ANTHROPIC_AUTH_TOKEN` |






### 保存并测试

保存并应用配置,然后重启 Claude Code。在 macOS 终端或 Windows PowerShell 里测试:

```bash
claude -p "用一句话确认连接正常"
```

能正常返回一句话说明本次请求成功；再用 `/status` 核对 Passion8 地址与令牌来源，确认实际配置。









上面这套配置适用于 **Claude Code CLI**。IDE 集成也可读取 CLI 配置，但当前 VS Code 扩展还有独立的启动前认证检查；仍显示登录时，应在 VS Code 用户设置配置 `claudeCode.environmentVariables`，见[官方网关说明](https://code.claude.com/docs/en/llm-gateway-connect#vs-code-extension)。**Claude Desktop 桌面端不吃这套配置**,它在 CC-Switch 里是另一个独立入口,需要单独再配一次,见下一节。




## 也接入 Claude Desktop 桌面端(可选)

Claude Code 和 Claude Desktop 是两个不同的应用:Claude Code 用 `~/.claude/settings.json`,Claude Desktop 用自己的配置。在 CC-Switch 里它们是**两个独立入口**——应用切换器里分别显示为「Claude」和「Claude Desktop」,后者图标右下角有一个小显示器标区分。所以桌面端要单独再配一次(内容和上面基本相同)。







### 切到 Claude Desktop 入口

在 CC-Switch 左侧应用切换器里选择 **Claude Desktop**(右下角带显示器小标的那个)。如果没看到,去「设置 → 通用 → 应用可见性」确认它没被隐藏。






### 添加供应商(或一键导入)

如果你刚才已经在 Claude Code 里配好了 Passion8,直接点 **「将 Claude Code 中已有的供应商导入」** 最省事。

也可以点右上角 **+** 手动添加,固定填写:

| 字段 | 值 |
| --- | --- |
| 名称 | `Passion8 Claude Desktop` |
| 接口地址/Base URL | `https://passion8.cc` |
| API Key | `sk-你的 Passion8 API Key` |

保持「需要模型映射」**关闭**(Passion8 走直连模式)。






### 启用并重启

在供应商卡片上点「启用」,然后**完全退出并重新打开 Claude Desktop**。




Claude Desktop 不像 Claude Code 那样热重载配置。每次切换供应商后,都必须彻底退出再重开,新配置才会生效。









## 手动配置

如果你不想装 CC-Switch,或希望直接控制环境变量和 `settings.json`,可以手动配置。






### macOS


### 1. 创建配置目录

推荐把配置写进用户级 `~/.claude/settings.json`,避免把 Key 放进项目仓库:

```bash
mkdir -p ~/.claude
```

### 2. 写入 settings.json

编辑 `~/.claude/settings.json`:

```json title="~/.claude/settings.json"
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://passion8.cc",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的 Passion8 API Key"
  }
}
```

### 3. 测试

保存后重新打开终端,进入项目目录测试:

```bash
claude -p "用一句话确认连接正常"
```

### 也可以用环境变量

写进 `~/.zshrc` 后对新开的终端生效:

```bash
echo 'export ANTHROPIC_BASE_URL="https://passion8.cc"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="sk-你的 Passion8 API Key"' >> ~/.zshrc
source ~/.zshrc
```




直接用 `echo` 写入真实 Key 可能留下 shell 历史。介意的话,用编辑器手动打开 `~/.zshrc` 或 `~/.claude/settings.json` 后粘贴。








### Windows


### 1. 创建配置目录

推荐把配置写进用户级 Claude Code 配置目录。先在 PowerShell 里创建目录:

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

### 2. 写入 settings.json

在打开的文件中写入:

```json title="%USERPROFILE%\\.claude\\settings.json"
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://passion8.cc",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的 Passion8 API Key"
  }
}
```

### 3. 测试

保存后重新打开 PowerShell,进入项目目录测试:

```powershell
claude -p "用一句话确认连接正常"
```

### 也可以用环境变量

`setx` 写入后,需要新开 PowerShell 窗口才生效:

```powershell
setx ANTHROPIC_BASE_URL "https://passion8.cc"
setx ANTHROPIC_AUTH_TOKEN "sk-你的 Passion8 API Key"
```








## 进阶配置模板

以下模型 ID 按 2026-10-11 官方模型目录核对：Sonnet 5.5、Opus 5.5、Fable 5.1、Haiku 5.5。官方提供不等于你的 Passion8 Key 已开放；复制前对照本站模型列表，不可用的档位应删除或改成你实际有权限的 ID。模板只保留 `ANTHROPIC_MODEL` 作为默认模型来源，不再同时写冲突的顶层 `model`。未验证的 `[1M]` 后缀不放入默认模板。

上面的最小配置用于基础接入。如果你已经熟悉 Claude Code 权限、缓存和模型切换,可以在 `~/.claude/settings.json` 里使用下面这份进阶模板。




这份模板不是新手默认配置。`bypassPermissions` 和 `skipDangerousModePermissionPrompt` 会减少确认弹窗,但也会放大误操作风险。只建议在你完全信任的本地项目、可回滚 Git 仓库、容器或一次性 VM 里使用。




```json title="~/.claude/settings.json"
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-你的 Passion8 API Key",
    "ANTHROPIC_BASE_URL": "https://passion8.cc",
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
    "CLAUDE_CODE_EFFORT_LEVEL": "auto",
    "DISABLE_AUTOUPDATER": "1",
    "DISABLE_BUG_COMMAND": "1",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0",
    "DISABLE_ERROR_REPORTING": "1",
    "DISABLE_TELEMETRY": "1",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL_NAME": "claude-sonnet-5-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL_NAME": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_FABLE_MODEL": "claude-fable-5-1",
    "ANTHROPIC_DEFAULT_FABLE_MODEL_NAME": "claude-fable-5-1",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-5-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME": "claude-haiku-5-5",
    "ANTHROPIC_MODEL": "claude-opus-5-5"
  },
  "attribution": {
    "commit": "",
    "pr": ""
  },
  "permissions": {
    "defaultMode": "bypassPermissions"
  },
  "skipDangerousModePermissionPrompt": true
}
```

默认不写 `ENABLE_PROMPT_CACHING_1H` 时,Claude Code 在 API/provider 场景会走 5 分钟 Prompt Cache TTL。只有你确认同一套大上下文会在 5 分钟后、1 小时内反复复用时,再单独加下面这一项:

```json title="可选:请求 1 小时 Prompt Cache TTL"
{
  "env": {
    "ENABLE_PROMPT_CACHING_1H": "1"
  }
}
```

### 关键字段解释

| 字段 | 作用 | 建议 |
| --- | --- | --- |
| `ANTHROPIC_BASE_URL` | 把 Claude Code 请求发到 Passion8 | 固定写 `https://passion8.cc`,不要带 `/v1` |
| `ANTHROPIC_AUTH_TOKEN` | Passion8 API Key | 必填,不要留空,不要提交到仓库 |
| `ENABLE_PROMPT_CACHING_1H` | 可选:请求 1 小时 Prompt Cache TTL | 默认不要写,未配置时 API/provider 走 5 分钟;大上下文、长间隔连续工作时再开 |
| `ENABLE_TOOL_SEARCH` | 延迟加载 MCP 工具定义 | 自定义网关默认不启用；仅在确认透传 `tool_reference` 后设置 `true`，否则请求可能失败 |
| `CLAUDE_CODE_EFFORT_LEVEL` | 默认思考强度 | 模板用 `auto` 跟随模型默认；可用强度因模型而异，该变量优先于 `/effort` 与 `--effort` |
| `ANTHROPIC_DEFAULT_*_MODEL` | 固定不同模型档位的默认模型 | 以 Passion8 模型广场实际可用 ID 为准 |
| `ANTHROPIC_MODEL` / `model` | 默认启动模型 | 本模板只设置前者；环境模型优先于文件 `model`，会话 `/model` 与 `--model` 可另行选择 |
| `attribution` | 控制提交与 PR 署名 | 取代已弃用的 `includeCoAuthoredBy`，不再重复设置旧字段 |
| `permissions.defaultMode = bypassPermissions` | 跳过大多数工具权限确认 | 高风险,只用于可信项目、容器、VM 或可回滚环境 |
| `skipDangerousModePermissionPrompt` | 不再显示危险模式确认提示 | 仅在你明确接受风险时开启 |

### 关于 1 小时缓存

`ENABLE_PROMPT_CACHING_1H=1` 不是默认推荐项。它适合反复加载同一套大上下文,并且两轮请求经常相隔 5 分钟以上、1 小时以内的场景。未配置时保持 5 分钟缓存,写入成本更低,也更适合作为默认配置。




1 小时缓存通常不能跨账号、跨模型或跨上游上下文复用。上游路由或缓存作用域发生变化时，后续请求可能无法复用原缓存；不要把命中作为保证。如果介意成本波动和重复缓存创建成本,保持默认 5 分钟即可。




更多缓存细节见 [Prompt 缓存](https://docs.passion8.cc/docs/claude-code/prompt-caching),权限风险见 [权限与模式](https://docs.passion8.cc/docs/claude-code/permissions)。

## 检查是否生效

先运行测试请求，并用 `/status` 与 Passion8 调用记录核对实际路由：

```bash
claude -p "用一句话说明当前项目是什么"
```

如果失败,优先检查:

| 检查项 | 正确值或做法 |
| --- | --- |
| Base URL | `https://passion8.cc` |
| Token 变量 | 使用 `ANTHROPIC_AUTH_TOKEN` |
| Token 内容 | 填 Passion8 API Key,不要带多余空格 |
| 终端 | 修改环境变量后要新开终端 |
| 项目配置 | 不要把个人 Key 写进可提交的 `.claude/settings.json` |

如果 `claude` 命令、PATH、代理、TLS 或登录异常,看 [安装与登录排错](https://docs.passion8.cc/docs/claude-code/install-troubleshooting)。如果报鉴权失败、模型不存在或运行中 API 错误,看 [常见问题](https://docs.passion8.cc/docs/claude-code/troubleshooting) 与 [错误参考](https://docs.passion8.cc/docs/claude-code/error-reference)。

## 接入常见问题

### 需要 Anthropic 账号或 Claude 订阅吗？

本机 Claude Code 使用本文的 Passion8 API Key 配置即可接入，无需 Anthropic OAuth 或 Claude 订阅。云端托管入口不由这份本地配置自动开通。

### 为什么 Claude Code 地址不带 /v1？

本文使用 Anthropic 兼容入口，`ANTHROPIC_BASE_URL` 填 `https://passion8.cc`。不要照抄 Codex 的 `https://passion8.cc/v1`；不同客户端的协议和地址要求不同。

### 如何选择模型，或在同一编辑器里切换四家模型？

使用 Passion8 控制台向你的令牌开放的精确模型 ID，在进阶模板的 `ANTHROPIC_MODEL` 中指定。要使用 Claude 官方面板，看 [VS Code 扩展教程](https://docs.passion8.cc/docs/claude-code/vscode)；要在一个扩展里切换 Claude、GPT、Gemini 和 Grok，看 [Cline 多模型配置](https://docs.passion8.cc/docs/cline)。

## 相关页面



- [安装 Claude Code](https://docs.passion8.cc/docs/claude-code/install): 安装 CLI、桌面端和官方 IDE 插件。
- [配置调试与 .claude 目录](https://docs.passion8.cc/docs/claude-code/configuration-debugging): 排查配置来源、settings 合并、Hooks、MCP、Skills、权限和本地数据。



## 本次字段核对

核对日期：2026-10-11。[官方模型目录](https://platform.claude.com/docs/en/about-claude/models/overview)、[环境变量](https://code.claude.com/docs/en/env-vars)、[配置字段](https://code.claude.com/docs/en/settings-reference)。仅核对文档，不代表对 Passion8 各模型完成实际调用测试。