# JetBrains IDE 集成

Claude Code 提供官方 JetBrains 插件，支持 IntelliJ IDEA、PyCharm、WebStorm、GoLand、PhpStorm、RubyMine、CLion、Rider、DataGrip、Android Studio 等所有基于 IntelliJ 平台的 IDE。本文介绍如何安装插件，并将其指向 QCode 网关，从而以更低成本调用 Claude Opus 5、Sonnet 5 等旗舰模型。

插件与命令行版本共享同一套配置：只要你的 `claude` CLI 能连上 QCode，IDE 插件也就能用。

## 前提条件

1. **Claude Code CLI 已安装并可正常使用**（用 `claude --version` 确认，不要对照文档里过期的数字）
   - 参考 [安装教程](/docs/getting-started/installation) 完成安装
   - 参考 [环境变量配置](/docs/getting-started/environment) 完成 QCode API 配置
   - 在终端运行 `claude --version` 确认可用

2. **JetBrains IDE 2024.1 或更高版本**（插件依赖较新的 IntelliJ 平台 API）

3. **一个 QCode API Key**（以 `cr_` 开头），同一个 Key 适用于全部接入点

## 安装步骤

### 步骤 1：安装 Claude Code 插件

1. 打开 JetBrains IDE

2. 进入 **Settings / Preferences** → **Plugins** → **Marketplace**

3. 搜索 **"Claude Code"**（发布者：Anthropic）

4. 点击 **Install**

5. 重启 IDE

> 提示：若你的网络无法直接访问 JetBrains Marketplace，可以从插件主页下载 `.zip` 包，再通过 **Plugins** → 齿轮图标 → **Install Plugin from Disk...** 离线安装。具体以 JetBrains 官方文档为准。

### 步骤 2：配置 QCode 接入

插件复用 Claude Code CLI 的配置，核心是两个环境变量：

```bash
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_your_api_key"
```

> **中国大陆用户**：把 `api.qcode.cc` 换成 `asia.qcode.cc` 通常更快更稳：
>
> ```bash
> export ANTHROPIC_BASE_URL="https://asia.qcode.cc/api"
> ```
>
> 四个域名 `api` / `asia` / `us` / `eu` 共用同一个 API Key，可按所在地区择优选择。`BASE_URL` 结尾**不要**带斜杠。

> **提示**：JetBrains IDE 会继承系统环境变量。如果你已在 `~/.zshrc` 或 `~/.bashrc` 中配置过，IDE 启动后会自动读取——前提是 IDE 是从已加载该配置的环境中启动的（见下方常见问题）。

如果你不想依赖全局环境变量，也可以只为单个项目设置（见 [常见问题](#环境变量未生效)）。

### 步骤 3：验证

1. 在 IDE 中按 `Cmd+Esc`（macOS）或 `Ctrl+Esc`（Windows/Linux）打开 Claude Code 面板

2. 输入一条简单消息（例如「你好」）测试连接

3. 若返回正常回复，说明插件已成功通过 QCode 连接

你也可以直接用 `curl` 验证网关本身可达（返回 `401` 表示路径正确、只是缺少鉴权，属于预期）：

```bash
curl -i https://api.qcode.cc/api/v1/messages
# HTTP/2 401  ← 路径正确，符合预期
```

## 使用方法

### 快捷键

| 快捷键 | 功能 |
|--------|------|
| `Cmd+Esc` / `Ctrl+Esc` | 打开 / 关闭 Claude Code 面板 |
| `Cmd+Option+K` / `Ctrl+Alt+K` | 在提示中插入当前文件引用（@file） |
| `Esc` | 中断当前生成 |

> 实际快捷键以插件版本与你的 Keymap 为准，可在 **Settings** → **Keymap** 中搜索 "Claude" 自定义。

### 核心能力

1. **代码解释**：选中代码 → 右键 → **Ask Claude**，让它解释这段逻辑

2. **代码生成**：在 Claude 面板中用自然语言描述需求，让它生成或修改代码

3. **错误修复**：把异常堆栈或报错信息发给 Claude 分析并给出修复

4. **代码重构**：选中目标代码，请求 Claude 优化结构、提取函数或补充测试

### 原生 Diff 视图

插件与 JetBrains 深度集成：当 Claude 提议修改文件时，会以 IDE **原生的并排 Diff 视图**展示改动，你可以逐处审阅、接受或拒绝，再写入磁盘。这比纯终端的 diff 更直观，也更安全。

### 与内置终端配合

JetBrains IDE 内置的 Terminal 也可以直接运行 `claude` 命令，与 CLI 功能完全一致。插件会自动把 IDE 当前打开的文件、选区作为上下文传给 CLI，二者协同使用体验最佳。

### 图像输入（视觉能力）

支持视觉的模型（Claude Opus 5 / Sonnet 5 以及 GPT-5.x 系列）可以**读取图片**作为输入：

- 把截图直接粘贴（`Ctrl+V`）到 Claude 面板
- 拖拽图片文件到对话框
- 在提示中引用图片文件路径

典型用途：根据设计稿/截图还原界面、根据报错截图排障、解读架构图与图表。

> 这是**图像输入**，不是图像生成。若要让模型**生成**图片，请使用 `gpt-image-2` 模型，详见 [gpt-image-2 图像生成](/docs/usage/image-2)。

### 模型选择

在 Claude 面板中可通过 `/model` 命令切换模型；不同模型经由 QCode 同一个 Key 调用。常用选择：

| 模型 | 输入 / 输出（每百万 token） | 上下文 | 适用场景 |
|------|------|--------|----------|
| `claude-opus-5` | $5 / $25 | 1M | 旗舰，复杂重构与架构推理 |
| `claude-opus-4-7` | — | 1M | 旗舰备选 |
| `claude-sonnet-5` | $2 / $10 | 1M | 日常编码，性价比均衡 |
| `claude-haiku-4-5` | $1 / $5 | 200K | 轻量任务、快速问答 |

> QCode 也支持 GPT-5.x、Gemini 等模型，但 JetBrains 的 Claude Code 插件主要面向 Anthropic 协议；GPT/Gemini 更适合在 Codex / Antigravity 等对应工具中使用。单价以 [qcode.cc/models](https://qcode.cc/models) 为准。`claude-sonnet-4-6` / `claude-opus-4-8` 等 4.x 仍在售。

### 高级用法

- **动态工作流（Dynamic Workflows）**：在提示中包含关键字 **`ultracode`** 或直接说「运行一个 workflow」，即可编排数十到数百个后台子代理并行处理大型任务（全仓代码审查、批量迁移、跨文件调研等）。子代理在后台运行，你可继续工作，用 `/workflows` 命令查看进度。它运行在 Claude Code 当前配置的模型上——指向 QCode 时同样生效。参见 [子代理](/docs/advanced/subagents)。

- **无头 / 自动化**：在 IDE 终端里同样可以用 `claude -p "<提示>"` 配合 `--output-format json|text|stream-json` 做脚本化调用，`json` 返回包含 `result`、`total_cost_usd`、`usage`、`session_id` 的结构化对象，便于 `jq` 解析。详见 [自动化与 CI/CD](/docs/advanced/headless)。

## 常见问题

### 插件不显示 Claude Code 面板？

1. 确认插件已安装并启用（**Settings** → **Plugins** → **Installed**）

2. 确认 Claude Code CLI 已全局安装：终端运行 `claude --version`，应打出版本号（以 [官方 Releases](https://github.com/anthropics/claude-code/releases) 为准）

3. 确认 IDE 版本 ≥ 2024.1

4. 重启 IDE；必要时执行 **File** → **Invalidate Caches / Restart**

### 环境变量未生效？

JetBrains IDE 可能未读取到 shell 配置文件中的环境变量（GUI 启动的进程往往不加载 `~/.zshrc`）。解决方法：

- **macOS**：从终端启动 IDE（如 `open -a "IntelliJ IDEA"`），而非从 Dock 点击；或使用 **Tools** → **Create Command-line Launcher** 后从终端启动

- **所有平台**：在 IDE 的 **Run/Debug Configurations** → **Environment variables** 中手动添加 `ANTHROPIC_BASE_URL` 与 `ANTHROPIC_AUTH_TOKEN`

- **持久化**：通过 JetBrains Toolbox 或 `*.vmoptions` / 系统级环境变量设置，确保每次启动都能读到

### 认证失败 / 401 / 403？

1. 检查 `ANTHROPIC_AUTH_TOKEN` 是否为有效的、以 `cr_` 开头的 QCode Key，且没有多余空格或引号

2. 确认 `ANTHROPIC_BASE_URL` 结尾**没有**斜杠，且路径为 `/api`（Anthropic 协议）

3. 直接 `curl -i https://api.qcode.cc/api/v1/messages`：返回 `401` 表示网关可达（仅缺鉴权），返回连接错误则是网络/代理问题

### 连接超时 / 公司代理后无法访问？

- 大陆用户优先切换到 `asia.qcode.cc`

- 若处于企业代理后，确认 IDE 的 **Settings** → **Appearance & Behavior** → **System Settings** → **HTTP Proxy** 配置正确，或为终端设置 `HTTPS_PROXY` 环境变量

- 确认防火墙允许 IDE 进程出站访问 `*.qcode.cc:443`

### 改了环境变量但 IDE 不感知？

环境变量在进程启动时读取一次。修改 `~/.zshrc` 或系统变量后，需**完全退出并重启 IDE**（而非仅重新打开窗口）才会生效。

## 下一步

- 查看 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths) 了解四个域名与各协议的 base URL

- 查看 [VS Code 集成](/docs/ide/vscode) 了解 VS Code 扩展

- 查看 [Cline 集成](/docs/ide/cline) 了解另一个 VS Code AI 扩展

- 查看 [CLI 技巧](/docs/usage/cli-tips) 了解终端使用技巧

> 想知道在 JetBrains 里跑哪款模型最划算？查看 [QCode 价格页](https://qcode.cc/pricing)，按预算挑选 Opus / Sonnet / Haiku。