# Claude Code
> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。
本文介绍如何在 Claude Code 中配置并使用方舟按量计费模型服务。
# 前提条件
在配置工具前，需要 [开通所需的模型服务](https://ark.volcengine.com/region:cn-beijing/openManagement?LLM=%7B%7D&OpenTokenDrawer=false)。
# 安装 Claude Code
前提条件：
* 安装 [Node.js 18 或更新版本环境](https://nodejs.org/en/download/)。
* Windows 用户需安装 [Git for Windows](https://git-scm.com/download/win)。
在命令行界面，执行以下命令安装 Claude Code。
```Bash
npm install -g @anthropic-ai/claude-code
```
安装结束后，执行以下命令查看安装结果，若显示版本号则安装成功。
```Bash
claude --version
```
# 配置 Claude Code
## 需配置的信息
如您对 Claude Code 熟悉、使用 CC Switch 等配置工具，或本地已有配置，可获取以下信息直接配置。
* **ANTHROPIC_BASE_URL**：`https://ark.cn-beijing.volces.com/api/compatible`。
* **ANTHROPIC_AUTH_TOKEN**：[获取API Key](https://ark.volcengine.com/region:cn-beijing/apikey)。
* **ANTHROPIC_MODEL**：按需选择模型并获取 Model ID。可用模型参见[模型列表](/docs/model-list)。
> **注意**
>
> 配置前注意清除以下环境变量，避免与旧配置冲突：
>
> ```Bash
> unset ANTHROPIC_AUTH_TOKEN
> unset ANTHROPIC_BASE_URL
> ```
>
> 若变量在 `~/.bashrc` / `~/.zshrc` 中，可以备份并同步删除对应变量。
## 手动配置
1. 创建并打开 `settings.json` 配置文件。文件路径因系统而异，具体操作如下：
**选项：macOS/Linux**
macOS/Linux 系统 Claude Code 配置文件路径：`~/.claude/settings.json`。
1. 如果在主目录下没有`.claude`目录，执行以下命令创建目录。
```Bash
mkdir -p ~/.claude
```
2. 创建并打开配置文件。
```Bash
nano ~/.claude/settings.json
```
**选项：Windows**
Windows 系统 Claude Code 配置文件路径：`%USERPROFILE%\.claude\settings.json`。以 CMD 命令行方式为例，操作如下。
1. 如果当前用户目录下没有`.claude`目录，执行以下命令创建目录。
```Bash
if not exist "%USERPROFILE%\.claude" mkdir "%USERPROFILE%\.claude"
```
2. 创建并打开配置文件。
```Bash
notepad "%USERPROFILE%\.claude\settings.json"
```
2. 编辑 `settings.json`，需要修改的配置信息如下：
* ``：替换为您的 [API Key](https://ark.volcengine.com/region:cn-beijing/apikey)。
* ``：替换为要使用的 [Model ID](/docs/model-list)。
```JSON
{
"env": {
"ANTHROPIC_AUTH_TOKEN": "",
"ANTHROPIC_BASE_URL": "https://ark.cn-beijing.volces.com/api/compatible",
"ANTHROPIC_MODEL": "",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "",
"CLAUDE_CODE_SUBAGENT_MODEL": "",
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
}
}
```
> **说明**
>
> * 推荐使用完整模型配置，并按任务复杂度选择模型：Haiku（轻量）、Sonnet（日常）、Opus（复杂）。
> * `CLAUDE_CODE_SUBAGENT_MODEL` 建议与主模型保持一致。
> * `ANTHROPIC_DEFAULT_HAIKU_MODEL` 建议设置为小尺寸模型，通常不会影响整体使用效果。
> * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 用于关闭 Claude Code 后台匿名遥测请求，设为 `"1"` 可避免额度被静默消耗。
3. 编辑或新增 `.claude.json` 文件，修改或新增 `hasCompletedOnboarding` 字段值为 `true`。
**选项：macOS/Linux**
1. 创建并打开配置文件。
```Bash
nano ~/.claude.json
```
2. 修改或新增的字段信息如下：
```JSON
{
"hasCompletedOnboarding": true
}
```
**选项：Windows**
1. 创建并打开配置文件。
```Bash
notepad "%USERPROFILE%\.claude.json"
```
2. 修改或新增的字段信息如下：
```JSON
{
"hasCompletedOnboarding": true
}
```
保存配置文件后，在新的终端窗口执行后续命令。
# 使用 Claude Code
1. 进入项目目录，执行 `claude` 命令，启动 Claude Code。
```Bash
cd my-project
claude
```
2. 启动后，选择信任此文件夹，允许 Claude Code 访问该文件夹中的文件。
3. 输入 `/status` 确认模型状态。
4. 在 Claude Code 中对话。
> 更多使用教程请参见 [Claude Code 官网](https://code.claude.com/docs/zh-CN/quickstart)。
# 其他操作
## 使用 Claude Code 的 Web Search 功能
> **说明**
>
> * Claude Code 通过兼容 Anthropic Messages 接口协议的服务调用豆包搜索能力。
> * 调用 Web Search 工具时，大模型可能会发起额外的 API 请求来总结搜索结果，因此会消耗额外的 token。
完成配置后，按以下步骤在 Claude Code 使用 Web Search 功能。
1. 登录方舟控制台，打开 [应用组件库 > 豆包搜索](https://ark.volcengine.com/region:cn-beijing/openManagement?advancedActiveKey=component&tab=DoubaoSearch) 标签页。
2. 在**豆包搜索 Custom 版**的**操作**列中点击**开通服务**。
3. 在 Claude Code 中直接提问，例如"GitHub 最近有哪些热门开源项目"。
## 使用 CC Switch
CC Switch 是一款跨平台桌面应用，专为使用 AI 编程工具的开发者设计。它帮助你统一管理 Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode、OpenClaw 和 Hermes 等受管应用的配置。
### 支持的平台
* Windows 10 及以上
* macOS 12 (Monterey) 及以上
* Linux Ubuntu 22.04+ / Debian 11+ / Fedora 34+（x64 / ARM64）
### 安装
更多安装方式和详细说明请参考 [CC Switch 官方文档](https://github.com/farion1231/cc-switch)。
**选项：macOS**
* Homebrew（推荐）：
```Bash
brew tap farion1231/ccswitch
brew install --cask cc-switch
```
* 手动下载：从 [Releases 页面](https://github.com/farion1231/cc-switch/releases) 下载 `.dmg`。
**选项：Linux**
* Arch 发行版：
```Bash
paru -S cc-switch-bin
```
* 其他发行版：根据架构（Debian / Ubuntu）从 [Releases 页面](https://github.com/farion1231/cc-switch/releases) 下载 `.deb` / `.rpm`，或者下载 `.AppImage`（通用）。
**选项：Windows**
从 [Releases 页面](https://github.com/farion1231/cc-switch/releases) 下载 `.msi` 安装包或 `.zip` 绿色版。
### 添加供应商
1. 在 CC Switch 中添加供应商：
1. 在主界面顶部图标栏选中 Claude Code 图标，点击右上角 **+** 进入添加新供应商。
2. 选择 **自定义配置**，填写以下信息：
* **API Key**：替换为您的 [API Key](https://ark.volcengine.com/region:cn-beijing/apikey)。
* **请求地址**：`https://ark.cn-beijing.volces.com/api/compatible`。
3. 展开高级选项，根据当前支持的模型范围，分别配置 Sonnet、Opus、Fable、Haiku 模型，可配置的模型见[模型列表](/docs/model-list)。
> **注意**
>
> 建议 Haiku 设置为小尺寸模型。
4. 选择右下角**添加**，完成供应商配置。
2. 回到首页，点击右侧**启用**按钮，新开一个 Claude Code 会话使配置生效。
## 安装使用 Claude Code IDE 插件
Claude Code IDE 插件依赖 Claude Code CLI 工具，需先完成 Claude Code 的安装及配置。
> 因 IDE 插件会迭代演进，以下内容仅供参考，具体的安装及使用可参考 [Visual Studio Code](https://code.claude.com/docs/en/vs-code)、[JetBrains IDEs](https://code.claude.com/docs/en/jetbrains)。
**选项：Claude Code VSCode 插件**
> **说明**
>
> Claude Code VSCode 插件支持在 VSCode 及基于 VSCode 的 IDE（如 Cursor、TraeCode 等）中使用。
### 安装插件
打开 VSCode，在扩展市场搜索 `claude code` 进行安装。
### 配置环境变量
1. 打开 VS Code 左下角设置，打开 **Extensions** - **Claude Code**。
2. 在 **Claude Code: Environment Variables** 区域单击 **Edit in settings.json**，修改 `claudeCode.environmentVariables`、`claudeCode.selectedModel`。
> **说明**
>
> * ``：替换为您的 [API Key](https://ark.volcengine.com/region:cn-beijing/apikey)。
> * ``：替换为要使用的模型。
> * 若在 Claude Code 对话框中输入 `/config`，插件仅返回可配置项的用法说明，不提供交互式编辑界面，请走设置入口。
```JSON
...
"claudeCode.environmentVariables": [
{
"name": "ANTHROPIC_BASE_URL",
"value": "https://ark.cn-beijing.volces.com/api/compatible"
},
{
"name": "ANTHROPIC_AUTH_TOKEN",
"value": ""
},
{
"name": "ANTHROPIC_MODEL",
"value": ""
}
],
"claudeCode.selectedModel": "",
...
```
保存配置后，新开一个窗口开始使用 Claude Code。
**选项：Claude Code JetBrains 插件**
> **说明**
>
> Claude Code JetBrains 插件支持 JetBrains 的系列 IDE，如 IntelliJ IDEA、PyCharm、WebStorm 等。
### 安装插件
打开 JetBrains IDE，在插件市场搜索 `claude code` 进行安装。
### 开始使用
安装完成后，重启 IDE 后，单击 Claude Code 图标，进入 Claude Code 页面开始使用。
## 接入 MCP Server 与 Skill
若内置工具未覆盖您的使用场景，可在 Claude Code 中接入二方、三方 MCP Server 与 Skill，扩展模型可用的能力。
### 获取 MCP Server
* **二方**：访问 [智能体工具商店](https://www.volcengine.com/mcp-marketplace)，获取火山引擎生态内的 MCP 工具（如巨量千川、知识库等），在 MCP 详情页获取服务地址与鉴权信息。
* **三方**：接入其他 MCP 市场提供的 MCP Server，或自行部署开源 MCP Server。
> **注意**
>
> 请从可信来源获取 MCP Server，其安全性与稳定性由提供方负责，接入前请确认其权限范围符合您的预期。
### 配置 MCP Server 与 Skill
1. 接入 MCP Server：执行以下命令添加（以 stdio 类型为例）。
```Bash
claude mcp add -- <启动命令> <启动参数>
```
添加完成后，可执行 `claude mcp list` 查看已接入的 MCP Server。更多说明（如 HTTP/SSE 类型、作用域管理）参考 [Claude Code 官方文档](https://code.claude.com/docs/en/mcp)。
2. 接入 Skill：将 Skill 目录放入 `~/.claude/skills/`（个人全局）或项目下的 `.claude/skills/` 目录即可。更多说明参考 [Claude Code Skills 说明](https://code.claude.com/docs/en/skills)。